display.texi 68.1 KB
Newer Older
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
3 4
@c   Free Software Foundation, Inc.

Dave Love's avatar
#  
Dave Love committed
5 6 7 8
@c See file emacs.texi for copying conditions.
@node Display, Search, Registers, Top
@chapter Controlling the Display

9 10 11 12
  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.
Dave Love's avatar
#  
Dave Love committed
13 14

@menu
15
* Scrolling::              Commands to move text up and down in a window.
16
* Recentering::            A scroll command that centers the current line.
17
* Auto Scrolling::         Redisplay scrolls text automatically when needed.
Richard M. Stallman's avatar
Richard M. Stallman committed
18
* Horizontal Scrolling::   Moving text left and right in a window.
19 20
* Narrowing::              Restricting display and editing to a portion
                             of the buffer.
21
* View Mode::              Viewing read-only buffers.
Richard M. Stallman's avatar
Richard M. Stallman committed
22
* Follow Mode::            Follow mode lets two windows scroll as one.
23
* Faces::                  How to change the display style using faces.
24
* Colors::                 Specifying colors for faces.
25
* Standard Faces::         Emacs' predefined faces.
26
* Text Scale::             Increasing or decreasing text size in a buffer.
27 28
* Font Lock::              Minor mode for syntactic highlighting using faces.
* Highlight Interactively:: Tell Emacs what text to highlight.
29
* Fringes::                Enabling or disabling window fringes.
30
* Displaying Boundaries::  Displaying top and bottom of the buffer.
Glenn Morris's avatar
Glenn Morris committed
31
* Useless Whitespace::     Showing possibly spurious trailing whitespace.
Dave Love's avatar
#  
Dave Love committed
32 33 34
* Selective Display::      Hiding lines with lots of indentation.
* Optional Mode Line::     Optional mode line display features.
* Text Display::           How text characters are normally displayed.
35
* Cursor Display::         Features for displaying the cursor.
36 37
* Line Truncation::        Truncating lines to fit the screen width instead
                             of continuing them to multiple screen lines.
Chong Yidong's avatar
Chong Yidong committed
38
* Visual Line Mode::       Word wrap and screen line-based editing.
Richard M. Stallman's avatar
Richard M. Stallman committed
39
* Display Custom::         Information on variables for customizing display.
Dave Love's avatar
#  
Dave Love committed
40 41
@end menu

42 43
@node Scrolling
@section Scrolling
44
@cindex scrolling
45

46 47 48
  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.
49

50 51 52
  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''
53 54 55 56 57 58 59 60 61
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.
62

63 64 65 66
  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:
67 68 69

@table @kbd
@item C-v
70 71
@itemx @key{next}
@itemx @key{PageDown}
72
Scroll forward by nearly a full window (@code{scroll-up-command}).
73
@item M-v
74 75
@itemx @key{prior}
@itemx @key{PageUp}
76
Scroll backward (@code{scroll-down-command}).
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
@end table

@kindex C-v
@kindex M-v
@kindex next
@kindex prior
@kindex PageDown
@kindex PageUp
@findex scroll-up-command
@findex scroll-down-command
  @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
whole window height.  The effect is to take the two lines at the
bottom of the window and put them at the top, followed by lines that
were not previously visible.  If point was in the text that scrolled
off the top, it ends up on the window's new topmost line.  The
@key{next} (or @key{PageDown}) key is equivalent to @kbd{C-v}.

  @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar
way.  The @key{prior} (or @key{PageUp}) key is equivalent to
@kbd{M-v}.

@vindex next-screen-context-lines
  The number of lines of overlap left by these scroll commands is
controlled by the variable @code{next-screen-context-lines}, whose
default value is 2.  You can supply the commands with a numeric prefix
argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave
point unchanged, so that the text and point move up or down together.
@kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa.

@vindex scroll-error-top-bottom
  By default, these commands signal an error (by beeping or flashing
the screen) if no more scrolling is possible, because the window has
reached the beginning or end of the buffer.  If you change the
variable @code{scroll-error-top-bottom} to @code{t}, the command moves
point to the farthest possible position.  If point is already there,
the command signals an error.

@vindex scroll-preserve-screen-position
@cindex @code{scroll-command} property
  Some users like scroll commands to keep point at the same screen
position, so that scrolling back to the same screen conveniently
returns point to its original position.  You can enable this behavior
via the variable @code{scroll-preserve-screen-position}.  If the value
is @code{t}, Emacs adjusts point to keep the cursor at the same screen
position whenever a scroll command moves it off-window, rather than
moving it to the topmost or bottommost line.  With any other
non-@code{nil} value, Emacs adjusts point this way even if the scroll
command leaves point in the window.  This variable affects all the
scroll commands documented in this section, as well as scrolling with
126
the mouse wheel (@pxref{Mouse Commands}); in general, it affects any
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
command that has a non-@code{nil} @code{scroll-command} property.
@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}.

@vindex scroll-up
@vindex scroll-down
@findex scroll-up-line
@findex scroll-down-line
  The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave
similarly to @code{scroll-up-command} and @code{scroll-down-command},
except they do not obey @code{scroll-error-top-bottom}.  Prior to
Emacs 24, these were the default commands for scrolling up and down.
The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line}
scroll the current window by one line at a time.  If you intend to use
any of these commands, you might want to give them key bindings
(@pxref{Init Rebinding}).

@node Recentering
@section Recentering

@table @kbd
@item C-l
Scroll the selected window so the current line is the center-most text
line; on subsequent consecutive invocations, make the current line the
top line, the bottom line, and so on in cyclic order.  Possibly
redisplay the screen too (@code{recenter-top-bottom}).

@item M-x recenter
Scroll the selected window so the current line is the center-most text
line.  Possibly redisplay the screen too.

157 158 159 160 161 162
@item C-M-l
Scroll heuristically to bring useful information onto the screen
(@code{reposition-window}).
@end table

@kindex C-l
163
@findex recenter-top-bottom
164 165 166 167
  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.
168 169 170 171

  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.
172
Each successive @kbd{C-l} cycles through these three positions.
173 174 175 176 177

@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
178
means to move the line to the specified screen line, while a
179
floating-point number between 0.0 and 1.0 specifies a percentage of
180 181 182 183 184 185
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}).
186

187 188 189 190 191 192 193
  You can also give @kbd{C-l} a prefix argument.  A plain prefix
argument, @kbd{C-u C-l}, simply recenters point.  A positive argument
@var{n} puts point @var{n} lines down from the top of the window.  An
argument of zero puts point on the topmost line.  A negative argument
@var{-n} puts point @var{n} lines from the bottom of the window.  When
given an argument, @kbd{C-l} does not clear the screen or cycle
through different screen positions.
194

195
@vindex recenter-redisplay
196
  If the variable @code{recenter-redisplay} has a non-@code{nil}
197 198 199 200 201 202
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
203
  The more primitive command @kbd{M-x recenter} behaves like
204
@code{recenter-top-bottom}, but does not cycle among screen positions.
205

206 207
@kindex C-M-l
@findex reposition-window
208 209 210
  @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
211 212
entire current defun onto the screen if possible.

213 214 215
@node Auto Scrolling
@section Automatic Scrolling

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

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

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

@cindex aggressive scrolling
@vindex scroll-up-aggressively
@vindex scroll-down-aggressively
242 243 244 245 246 247 248 249 250 251 252 253
  When the window does scroll by a distance longer than
@code{scroll-step}, you can control how aggressively it scrolls by
setting the variables @code{scroll-up-aggressively} and
@code{scroll-down-aggressively}.  The value of
@code{scroll-up-aggressively} should be either @code{nil}, or a
fraction @var{f} between 0 and 1.  A fraction specifies where on the
screen to put point when scrolling upward, i.e.@: forward.  When point
goes off the window end, the new start position is chosen to put point
@var{f} parts of the window height from the bottom margin.  Thus,
larger @var{f} means more aggressive scrolling: more new text is
brought into view.  The default value, @code{nil}, is equivalent to
0.5.
254 255

  Likewise, @code{scroll-down-aggressively} is used for scrolling
256 257
down, i.e.@: backward.  The value specifies how far point should be
placed from the top margin of the window; thus, as with
258
@code{scroll-up-aggressively}, a larger value is more aggressive.
259

260 261 262
  These two variables are ignored if either @code{scroll-step} or
@code{scroll-conservatively} are set to a non-zero value.

263 264 265 266 267
  Note that @code{scroll-margin}, described below, limits the amount
of scrolling so as to put point outside of the top or bottom margin,
even if aggressive scrolling specifies a fraction @var{f} that is
larger than the window portion between the top and the bottom margins.

268 269 270
@vindex scroll-margin
  The variable @code{scroll-margin} restricts how close point can come
to the top or bottom of a window.  Its value is a number of screen
271 272 273
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.
274 275 276 277 278

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

279
@vindex auto-hscroll-mode
280
  @dfn{Horizontal scrolling} means shifting all the lines sideways
281 282 283 284 285 286
within a window, so that some of the text near the left margin is not
displayed.  When the text in a window is scrolled horizontally, text
lines are truncated rather than continued (@pxref{Line Truncation}).
If a window shows truncated lines, Emacs performs automatic horizontal
scrolling whenever point moves off the left or right edge of the
screen.  To disable automatic horizontal scrolling, set the variable
287 288
@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
289
screen, the cursor disappears to indicate that.  (On text-only
290
terminals, the cursor is left at the edge instead.)
291 292 293

@vindex hscroll-margin
  The variable @code{hscroll-margin} controls how close point can get
294 295 296 297
to the window's edges before automatic scrolling occurs.  It is
measured in columns.  For example, if the value is 5, then moving
point within 5 columns of an edge causes horizontal scrolling away
from that edge.
298 299 300 301 302 303 304 305 306 307 308

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

  You can also perform explicit horizontal scrolling with the
following commands:
309 310 311 312 313 314 315 316 317 318 319 320

@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
321 322 323 324 325 326 327 328 329 330 331 332
  @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.
333 334 335 336 337 338 339

  @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.
340 341 342 343 344 345

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

346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
@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}.

412 413 414 415 416
@node View Mode
@section View Mode
@cindex View mode
@cindex mode, View

417 418 419
@kindex s @r{(View mode)}
@kindex SPC @r{(View mode)}
@kindex DEL @r{(View mode)}
420 421 422 423
  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
424 425
windowful, @key{DEL} to scroll backward, and @kbd{s} to start an
incremental search.
426

427 428 429 430 431 432 433 434
@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.
435 436 437 438 439 440 441

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

442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463
@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.

464
@node Faces
465
@section Text Faces
466 467
@cindex faces

468
  Emacs can display text in several different styles, called
Richard M. Stallman's avatar
Richard M. Stallman committed
469
@dfn{faces}.  Each face can specify various @dfn{face attributes},
470 471 472 473 474 475 476 477 478 479 480 481 482 483
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}).

  It's possible for a given face to look different in different
frames.  For instance, some text-only terminals do not support all
face attributes, particularly font, height, and width, and some
484
support a limited range of colors.
485

486 487 488 489 490 491
@cindex background color
@cindex default face
  You can customize a face to alter its appearance, and save those
changes for future Emacs sessions.  @xref{Face Customization}.  A face
does not have to specify every single attribute; often it inherits
most attributes from another face.  Any ultimately unspecified
492 493 494 495
attribute is taken from the face named @code{default}.

  The @code{default} face is the default for displaying text, and all
of its attributes are specified.  Its background color is also used as
496
the frame's background color.  @xref{Colors}.
497 498 499 500 501 502 503 504 505

@cindex cursor face
  Another special face is the @code{cursor} face.  On graphical
displays, the background color of this face is used to draw the text
cursor.  None of the other attributes of this face have any effect;
the foreground color for text under the cursor is taken from the
background color of the underlying text.  On text terminals, the
appearance of the text cursor is determined by the terminal, not by
the @code{cursor} face.
506 507 508

  You can also use X resources to specify attributes of any particular
face.  @xref{Resources}.
509

510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526
  Emacs can display variable-width fonts, but some Emacs commands,
particularly indentation commands, do not account for variable
character display widths.  Therefore, we recommend not using
variable-width fonts for most faces, particularly those assigned by
Font Lock mode.

@node Colors
@section Colors for Faces
@cindex color name
@cindex RGB triplet

  Faces can have various foreground and background colors.  When you
specify a color for a face---for instance, when customizing the face
(@pxref{Face Customization})---you can use either a @dfn{color name}
or an @dfn{RGB triplet}.

@findex list-colors-display
527
@vindex list-colors-sort
528 529
  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
530 531 532 533 534 535 536 537 538
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-only 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-only terminals;
if a face is given a color specified by an X11 color name, it is
displayed using the closest-matching terminal color.
539 540 541 542 543 544 545 546 547 548 549 550 551

  An RGB triplet is a string of the form @samp{#RRGGBB}.  Each of the
R, G, and B components is a hexadecimal number specifying the
component's relative intensity, one to four digits long (usually two
digits are used).  The components must have the same number of digits.
For hexadecimal values A to F, either upper or lower case are
acceptable.

  The @kbd{M-x list-colors-display} command also shows the equivalent
RGB triplet for each named color.  For instance, @samp{medium sea
green} is equivalent to @samp{#3CB371}.

@cindex face colors, setting
552 553
@findex set-face-foreground
@findex set-face-background
554 555 556 557
  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.
558 559 560
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
561
foreground and background colors for a specific frame; @xref{Frame
562 563
Parameters}.

564 565 566
@node Standard Faces
@section Standard Faces

Richard M. Stallman's avatar
Richard M. Stallman committed
567 568
  Here are the standard faces for specifying text appearance.  You can
apply them to specific text when you want the effects they produce.
569 570 571

@table @code
@item default
Richard M. Stallman's avatar
Richard M. Stallman committed
572
This face is used for ordinary text that doesn't specify any face.
573
Its background color is used as the frame's background color.
574
@item bold
575
This face uses a bold variant of the default font.
576
@item italic
577
This face uses an italic variant of the default font.
578
@item bold-italic
579
This face uses a bold italic variant of the default font.
580 581 582
@item underline
This face underlines text.
@item fixed-pitch
583 584 585
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.
586
@item variable-pitch
587
This face forces use of a variable-width font.
588 589 590 591
@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.
592 593 594 595 596 597 598 599
@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
600 601
This face is used for text highlighting in various contexts, such as
when the mouse cursor is moved over a hyperlink.
602
@item isearch
603
This face is used to highlight the current Isearch match
604
(@pxref{Incremental Search}).
Richard M. Stallman's avatar
Richard M. Stallman committed
605
@item query-replace
606
This face is used to highlight the current Query Replace match
607
(@pxref{Replace}).
608
@item lazy-highlight
609 610
This face is used to highlight ``lazy matches'' for Isearch and Query
Replace (matches other than the current one).
611
@item region
612 613 614
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.
615 616 617 618
@item secondary-selection
This face is used for displaying a secondary X selection (@pxref{Secondary
Selection}).
@item trailing-whitespace
619
The face for highlighting excess spaces and tabs at the end of a line
620 621
when @code{show-trailing-whitespace} is non-@code{nil} (@pxref{Useless
Whitespace}).
622
@item escape-glyph
623 624 625
The face for displaying control characters and escape sequences
(@pxref{Text Display}).
@item nobreak-space
626
The face for displaying ``no-break'' space characters (@pxref{Text
627
Display}).
628 629
@end table

630 631
  The following faces control the appearance of parts of the Emacs
frame:
632 633

@table @code
634
@item mode-line
635 636
This face is used for the mode line of the currently selected window,
and for menu bars when toolkit menus are not used.  By default, it's
Richard M. Stallman's avatar
Richard M. Stallman committed
637
drawn with shadows for a ``raised'' effect on graphical displays, and
638
drawn as the inverse of the default face on non-windowed terminals.
639 640 641
@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
Richard M. Stallman's avatar
Richard M. Stallman committed
642 643
non-@code{nil}).  This face inherits from @code{mode-line}, so changes
in that face affect mode lines in all windows.
644 645 646 647
@item mode-line-highlight
Like @code{highlight}, but used for portions of text on mode lines.
@item mode-line-buffer-id
This face is used for buffer identification parts in the mode line.
648
@item header-line
Richard M. Stallman's avatar
Richard M. Stallman committed
649 650 651 652
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.
653
@item vertical-border
654 655
This face is used for the vertical divider between windows on
text-only terminals.
656
@item minibuffer-prompt
657 658
@cindex @code{minibuffer-prompt} face
@vindex minibuffer-prompt-properties
659
This face is used for the prompt strings displayed in the minibuffer.
660 661
By default, Emacs automatically adds this face to the value of
@code{minibuffer-prompt-properties}, which is a list of text
662 663
properties used to display the prompt text.  (This variable takes
effect when you enter the minibuffer.)
664
@item fringe
665
@cindex @code{fringe} face
666 667
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
668
between the text area and the window's right and left borders.)
669
@xref{Fringes}.
670
@item cursor
671 672
The @code{:background} attribute of this face specifies the color of
the text cursor.  @xref{Cursor Display}.
673 674 675 676
@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}.
677 678
@item mouse
This face determines the color of the mouse pointer.
679 680 681 682 683 684 685 686 687 688 689
@end table

  The following faces likewise control the appearance of parts of the
Emacs frame, but only on text-only terminals, or when Emacs is built
on X with no toolkit support.  (For all other cases, the appearance of
the respective frame elements is determined by system-wide settings.)

@table @code
@item scroll-bar
This face determines the visual appearance of the scroll bar.
@xref{Scroll Bars}.
690
@item tool-bar
Richard M. Stallman's avatar
Richard M. Stallman committed
691
This face determines the color of tool bar icons.  @xref{Tool Bars}.
692
@item menu
693 694 695 696
@cindex menu bar appearance
@cindex @code{menu} face, no effect if customized
@cindex customization of @code{menu} face
This face determines the colors and font of Emacs's menus.  @xref{Menu
697
Bars}.
698 699
@end table

700 701
@node Text Scale
@section Text Scale
702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717

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

  The final key of these commands may be repeated without the leading
@kbd{C-x}.  For instance, @kbd{C-x C-= C-= C-=} increases the face
718 719 720 721 722
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}.  As an exception, a numeric argument of 0
to the @code{text-scale-adjust} command restores the default height,
similar to typing @kbd{C-x C-0}.
723 724 725 726 727 728 729 730 731 732 733

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

Miles Bader's avatar
Miles Bader committed
734 735
@cindex set buffer face height
@findex text-scale-set
736 737 738
  The command @code{text-scale-set} scales the height of the default
face in the current buffer to an absolute level specified by its
prefix argument.
Miles Bader's avatar
Miles Bader committed
739

740
@findex text-scale-mode
741 742 743
  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.
744

745 746 747 748 749 750
@node Font Lock
@section Font Lock mode
@cindex Font Lock mode
@cindex mode, Font Lock
@cindex syntax highlighting and coloring

751
  Font Lock mode is a minor mode, always local to a particular buffer,
752 753 754 755
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.
756 757

@findex font-lock-mode
758 759 760 761
  Font Lock mode is enabled by default.  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.
762 763 764

@findex global-font-lock-mode
@vindex global-font-lock-mode
765 766 767 768 769
  To toggle Font Lock mode in all buffers, type @kbd{M-x
global-font-lock-mode}.  To impose this setting for future Emacs
sessions, customize the variable @code{global-font-lock-mode}
(@pxref{Easy Customization}), or add the following line to your init
file:
770 771

@example
Chong Yidong's avatar
Chong Yidong committed
772
(global-font-lock-mode 0)
773 774
@end example

775 776
@noindent
If you have disabled Global Font Lock mode, you can still enable Font
Richard M. Stallman's avatar
Richard M. Stallman committed
777
Lock for specific major modes by adding the function
778 779
@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:
Chong Yidong's avatar
Chong Yidong committed
780 781

@example
782
(add-hook 'c-mode-hook 'font-lock-mode)
Chong Yidong's avatar
Chong Yidong committed
783
@end example
Richard M. Stallman's avatar
Richard M. Stallman committed
784

785 786
  Font Lock mode uses several specifically named faces to do its job,
including @code{font-lock-string-face}, @code{font-lock-comment-face},
Richard M. Stallman's avatar
Richard M. Stallman committed
787 788 789 790
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}.
791 792

@vindex font-lock-maximum-decoration
793 794 795 796 797 798 799 800
  You can customize the variable @code{font-lock-maximum-decoration}
to alter the amount of fontification applied by Font Lock mode, for
major modes that support this feature.  The value 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).  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
801 802

@example
803
'((c-mode . 1) (c++-mode . 1)))
804 805 806
@end example

@vindex font-lock-beginning-of-syntax-function
807 808 809
@cindex incorrect fontification
@cindex parenthesis in column zero and fontification
@cindex brace in column zero and fontification
810 811
  Comment and string fontification (or ``syntactic'' fontification)
relies on analysis of the syntactic structure of the buffer text.  For
812 813
the sake of speed, some modes, including Lisp mode, rely on a special
convention: an open-parenthesis or open-brace in the leftmost column
814
always defines the beginning of a defun, and is thus always outside
Juanma Barranquero's avatar
Juanma Barranquero committed
815
any string or comment.  Therefore, you should avoid placing an
816 817
open-parenthesis or open-brace in the leftmost column, if it is inside
a string or comment.  @xref{Left Margin Paren}, for details.
818

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

@findex font-lock-add-keywords
833 834 835 836 837
  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:
838 839

@example
840 841 842
(add-hook 'c-mode-hook
          (lambda ()
           (font-lock-add-keywords nil
843 844
            '(("\\<\\(FIXME\\):" 1
               font-lock-warning-face t)))))
845 846
@end example

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

853 854 855
@cindex just-in-time (JIT) font-lock
@cindex background syntax highlighting
  Fontifying large buffers can take a long time.  To avoid large
856 857 858 859 860 861
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
862
customization group @samp{jit-lock}.  @xref{Specific Customization}.
863

864
@node Highlight Interactively
Richard M. Stallman's avatar
Richard M. Stallman committed
865
@section Interactive Highlighting
866 867
@cindex highlighting by matching
@cindex interactive highlighting
Richard M. Stallman's avatar
Richard M. Stallman committed
868
@cindex Highlight Changes mode
869

Richard M. Stallman's avatar
Richard M. Stallman committed
870
@findex highlight-changes-mode
871
Highlight Changes mode is a minor mode that @dfn{highlights} the parts
872
of the buffer that were changed most recently, by giving that text a
873 874
different face.  To enable or disable Highlight Changes mode, use
@kbd{M-x highlight-changes-mode}.
875

Richard M. Stallman's avatar
Richard M. Stallman committed
876
@cindex Hi Lock mode
877
@findex hi-lock-mode
878 879 880 881 882 883 884 885
  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.
Richard M. Stallman's avatar
Richard M. Stallman committed
886 887 888 889

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

@table @kbd
@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w h
@findex highlight-regexp
895
Highlight text that matches @var{regexp} using face @var{face}
Richard M. Stallman's avatar
Richard M. Stallman committed
896 897 898 899 900
(@code{highlight-regexp}).  The highlighting will remain as long as
the buffer is loaded.  For example, to highlight all occurrences of
the word ``whim'' using the default face (a yellow background)
@kbd{C-x w h whim @key{RET} @key{RET}}.  Any face can be used for
highlighting, Hi Lock provides several of its own and these are
901 902
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.
Richard M. Stallman's avatar
Richard M. Stallman committed
903 904 905

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

@item C-x w r @var{regexp} @key{RET}
@kindex C-x w r
@findex unhighlight-regexp
910
Unhighlight @var{regexp} (@code{unhighlight-regexp}).
Richard M. Stallman's avatar
Richard M. Stallman committed
911 912 913 914 915 916 917 918 919

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

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

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

937 938 939
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}).
940 941 942 943

@item C-x w i
@kindex C-x w i
@findex hi-lock-find-patterns
944 945 946 947
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
948
including different faces for different parenthesized parts of the
949 950
match), and finally use this command (@code{hi-lock-find-patterns}) to
have Hi Lock highlight the edited patterns.
951

952
@vindex hi-lock-file-patterns-policy
953
The variable @code{hi-lock-file-patterns-policy} controls whether Hi
954 955 956 957 958 959 960 961
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.
962 963 964 965

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

968 969 970 971
@node Fringes
@section Window Fringes
@cindex fringes

972 973 974
@findex set-fringe-style
@findex fringe-mode
  On graphical displays, each Emacs window normally has narrow
975 976
@dfn{fringes} on the left and right edges.  The fringes are used to
display symbols that provide information about the text in the window.
977 978 979
You can type @kbd{M-x fringe-mode} to disable the fringes, or modify
their width.  This command affects fringes in all frames; to modify
fringes on the selected frame only, use @kbd{M-x set-fringe-style}.
980 981

  The most common use of the fringes is to indicate a continuation
982 983 984 985 986 987 988
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
989
swapped.
990

991
  The fringes indicate line truncation with short horizontal arrows
992
meaning ``there's more text on this line which is scrolled
993 994 995 996 997 998
horizontally out of view.''  Clicking the mouse on one of the arrows
scrolls the display horizontally in the direction of the arrow.

  The fringes can also indicate other things, such as buffer
boundaries (@pxref{Displaying Boundaries}), and where a program you
are debugging is executing (@pxref{Debuggers}).
999

1000 1001 1002 1003 1004 1005
@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.
1006

1007 1008 1009 1010
@node Displaying Boundaries
@section Displaying Boundaries

@vindex indicate-buffer-boundaries
1011
  On graphical displays, Emacs can indicate the buffer boundaries in
1012 1013 1014 1015
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.
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035

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

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

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

1036 1037 1038 1039 1040 1041 1042 1043 1044
@node Useless Whitespace
@section Useless Whitespace

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

1047 1048 1049 1050
  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}.
1051 1052 1053 1054 1055 1056 1057 1058 1059

  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
1060 1061 1062
  Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
whitespace within the buffer.  If the region is active, it deletes all
trailing whitespace in the region instead.
1063

1064
@vindex indicate-empty-lines
1065 1066
@cindex unused lines
@cindex fringes, and unused line indication
1067 1068
  On graphical displays, Emacs can indicate unused lines at the end of
the window with a small image in the left fringe (@pxref{Fringes}).
1069 1070 1071 1072 1073 1074 1075
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)}.
1076

1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092
@cindex Whitespace mode
@cindex mode, Whitespace
@findex whitespace-mode
@vindex whitespace-style
  Whitespace mode is a buffer-local minor mode that lets you
``visualize'' many kinds of whitespace in the buffer, by either
drawing the whitespace characters with a special face or displaying
them as special glyphs.  To toggle this mode, type @kbd{M-x
whitespace-mode}.  The kinds of whitespace visualized are determined
by the list variable @code{whitespace-style}.  Here is a partial list
of possible elements (see the variable's documentation for the full
list):

@table @code
@item face
Enable all visualizations which use special faces.  This element has a
Paul Eggert's avatar
Paul Eggert committed
1093
special meaning: if it is absent from the list, none of the other
1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126
visualizations take effect except @code{space-mark}, @code{tab-mark},
and @code{newline-mark}.

@item trailing
Highlight trailing whitespace.

@item tabs
Highlight tab characters.

@item spaces
Highlight space and non-breaking space characters.

@item lines
@vindex whitespace-line-column
Highlight lines longer than 80 lines.  To change the column limit,
customize the variable @code{whitespace-line-column}.

@item newline
Highlight newlines.

@item empty
Highlight empty lines.

@item space-mark
Draw space and non-breaking characters with a special glyph.

@item tab-mark
Draw tab characters with a special glyph.

@item newline-mark
Draw newline characters with a special glyph.
@end table

Dave Love's avatar
#  
Dave Love committed
1127 1128
@node Selective Display
@section Selective Display
1129
@cindex selective display
Dave Love's avatar
#  
Dave Love committed
1130 1131 1132
@findex set-selective-display
@kindex C-x $

1133 1134 1135
  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.
Dave Love's avatar
#  
Dave Love committed
1136

Luc Teirlinck's avatar
Luc Teirlinck committed
1137 1138 1139 1140 1141 1142
  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.
Dave Love's avatar
#  
Dave Love committed
1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161

  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.

Richard M. Stallman's avatar
Richard M. Stallman committed
1162 1163 1164
  See also @ref{Outline Mode} for another way to hide part of
the text in a buffer.

Dave Love's avatar
#  
Dave Love committed
1165 1166 1167
@node Optional Mode Line
@section Optional Mode Line Features

1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185
@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.

1186 1187
@cindex line number display
@cindex display of line number
Dave Love's avatar
#  
Dave Love committed
1188 1189 1190 1191
@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
1192
after the buffer percentage @var{pos}, with the letter @samp{L} to
1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204
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.
Dave Love's avatar
#  
Dave Love committed
1205

1206 1207 1208
@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.
Richard M. Stallman's avatar
Richard M. Stallman committed
1209 1210 1211
Thus, it isn't suitable as an argument to @code{goto-line}.  (Use
@code{what-line} command to see the line number relative to the whole
file.)
1212

Dave Love's avatar
#  
Dave Love committed
1213 1214
@vindex line-number-display-limit
  If the buffer is very large (larger than the value of
1215 1216 1217 1218
@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}.
1219 1220 1221

@vindex line-number-display-limit-width
  Line-number computation can also be slow if the lines in the buffer