*** empty log message ***
[emacs.git] / man / display.texi
blobc652b47787ab83361b4640990c3809849525354c
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000, 2001, 2002
3 @c   Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Display, Search, Registers, Top
6 @chapter Controlling the Display
8   Since only part of a large buffer fits in the window, Emacs tries to
9 show a part that is likely to be interesting.  Display-control commands
10 allow you to specify which part of the text you want to see, and how to
11 display it.
13 @menu
14 * Faces::                  How to change the display style using faces.
15 * Font Lock::              Minor mode for syntactic highlighting using faces.
16 * Highlight Changes::      Using colors to show where you changed the buffer.
17 * Highlight Interactively:: Tell Emacs what text to highlight.
18 * Scrolling::              Moving text up and down in a window.
19 * Horizontal Scrolling::   Moving text left and right in a window.
20 * Fringes::                Enabling or disabling window fringes.
21 * Useless Whitespace::     Showing possibly-spurious trailing whitespace.
22 * Follow Mode::            Follow mode lets two windows scroll as one.
23 * Selective Display::      Hiding lines with lots of indentation.
24 * Optional Mode Line::     Optional mode line display features.
25 * Text Display::           How text characters are normally displayed.
26 * Cursor Display::         Features for displaying the cursor.
27 * Display Custom::         Information on variables for customizing display.
28 @end menu
30 @node Faces
31 @section Using Multiple Typefaces
32 @cindex faces
34   You can specify various styles for displaying text using
35 @dfn{faces}.  Each face can specify various @dfn{face attributes},
36 such as the font family, the height, weight and slant of the
37 characters, the foreground and background color, and underlining or
38 overlining.  A face does not have to specify all of these attributes;
39 often it inherits most of them from another face.
41   On a window system, all the Emacs face attributes are meaningful.
42 On a character terminal, only some of them work.  Some character
43 terminals support inverse video, bold, and underline attributes; some
44 support colors.  Character terminals generally do not support changing
45 the height and width or the font family.
47   Features which rely on text in multiple faces (such as Font Lock mode)
48 will also work on non-windowed terminals that can display more than one
49 face, whether by colors or underlining and emboldening.  This includes
50 the console on GNU/Linux, an @code{xterm} which supports colors, the
51 MS-DOS display (@pxref{MS-DOS}), and the MS-Windows version invoked with
52 the @option{-nw} option.  Emacs determines automatically whether the
53 terminal has this capability.
55   You control the appearance of a part of the text in the buffer by
56 specifying the face or faces to use for it.  The style of display used
57 for any given character is determined by combining the attributes of
58 all the applicable faces specified for that character.  Any attribute
59 that isn't specified by these faces is taken from the @code{default} face,
60 whose attributes reflect the default settings of the frame itself.
62   Enriched mode, the mode for editing formatted text, includes several
63 commands and menus for specifying faces for text in the buffer.
64 @xref{Format Faces}, for how to specify the font for text in the
65 buffer.  @xref{Format Colors}, for how to specify the foreground and
66 background color.
68 @cindex face colors, setting
69 @findex set-face-foreground
70 @findex set-face-background
71   To alter the appearance of a face, use the customization buffer.
72 @xref{Face Customization}.  You can also use X resources to specify
73 attributes of particular faces (@pxref{Resources}).  Alternatively,
74 you can change the foreground and background colors of a specific face
75 with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
76 These commands prompt in the minibuffer for a face name and a color
77 name, with completion, and then set that face to use the specified
78 color.  Changing the colors of the @code{default} face also changes
79 the foreground and background colors on all frames, both existing and
80 those to be created in the future.  (You can also set foreground and
81 background colors for the current frame only; see @ref{Frame
82 Parameters}.)
84   Emacs 21 can correctly display variable-width fonts, but Emacs
85 commands that calculate width and indentation do not know how to
86 calculate variable widths.  This can sometimes lead to incorrect
87 results when you use variable-width fonts.  In particular, indentation
88 commands can give inconsistent results, so we recommend you avoid
89 variable-width fonts for editing program source code.  Filling will
90 sometimes make lines too long or too short.  We plan to address these
91 issues in future Emacs versions.
93 @findex list-faces-display
94   To see what faces are currently defined, and what they look like, type
95 @kbd{M-x list-faces-display}.  It's possible for a given face to look
96 different in different frames; this command shows the appearance in the
97 frame in which you type it.  Here's a list of the standard defined
98 faces:
100 @table @code
101 @item default
102 This face is used for ordinary text that doesn't specify any other face.
103 @item mode-line
104 This face is used for the mode line of the currently selected window.
105 By default, it's drawn with shadows for a ``raised'' effect on window
106 systems, and drawn as the inverse of the default face on non-windowed
107 terminals.  @xref{Display Custom}.
108 @item mode-line-inactive
109 Like @code{mode-line}, but used for mode lines of the windows other
110 than the selected one (if @code{mode-line-in-non-selected-windows} is
111 non-@code{nil}).  This face inherits from @code{mode-line}, so changes
112 in that face affect mode lines in all windows.
113 @item header-line
114 Similar to @code{mode-line} for a window's header line.  Most modes
115 don't use the header line, but the Info mode does.
116 @item minibuffer-prompt
117 This face is used for the prompt strings displayed in the minibuffer.
118 @item highlight
119 This face is used for highlighting portions of text, in various modes.
120 For example, mouse-sensitive text is highlighted using this face.
121 @item isearch
122 This face is used for highlighting Isearch matches.
123 @item lazy-highlight
124 This face is used for lazy highlighting of Isearch and Query Replace
125 matches other than the current one.
126 @item region
127 This face is used for displaying a selected region (when Transient Mark
128 mode is enabled---see below).
129 @item secondary-selection
130 This face is used for displaying a secondary X selection (@pxref{Secondary
131 Selection}).
132 @item bold
133 This face uses a bold variant of the default font, if it has one.
134 @item italic
135 This face uses an italic variant of the default font, if it has one.
136 @item bold-italic
137 This face uses a bold italic variant of the default font, if it has one.
138 @item underline
139 This face underlines text.
140 @item fixed-pitch
141 The basic fixed-pitch face.
142 @item fringe
143 @cindex fringe
144 The face for the fringes to the left and right of windows on graphic
145 displays.  (The fringes are the narrow portions of the Emacs frame
146 between the text area and the window's right and left borders.)
147 @item scroll-bar
148 This face determines the visual appearance of the scroll bar.
149 @item border
150 This face determines the color of the frame border.
151 @item cursor
152 This face determines the color of the cursor.
153 @item mouse
154 This face determines the color of the mouse pointer.
155 @item tool-bar
156 This is the basic tool-bar face.  No text appears in the tool bar, but the
157 colors of this face affect the appearance of tool bar icons.
158 @item tooltip
159 This face is used for tooltips.
160 @item menu
161 This face determines the colors and font of Emacs's menus.  Setting the
162 font of LessTif/Motif menus is currently not supported; attempts to set
163 the font are ignored in this case.
164 @item trailing-whitespace
165 The face for highlighting trailing whitespace when
166 @code{show-trailing-whitespace} is non-@code{nil}; see @ref{Useless
167 Whitespace}.
168 @item variable-pitch
169 The basic variable-pitch face.
170 @end table
172 @cindex @code{region} face
173   When Transient Mark mode is enabled, the text of the region is
174 highlighted when the mark is active.  This uses the face named
175 @code{region}; you can control the style of highlighting by changing the
176 style of this face (@pxref{Face Customization}).  @xref{Transient Mark},
177 for more information about Transient Mark mode and activation and
178 deactivation of the mark.
180   One easy way to use faces is to turn on Font Lock mode.  This minor
181 mode, which is always local to a particular buffer, arranges to
182 choose faces according to the syntax of the text you are editing.  It
183 can recognize comments and strings in most languages; in several
184 languages, it can also recognize and properly highlight various other
185 important constructs.  @xref{Font Lock}, for more information about
186 Font Lock mode and syntactic highlighting.
188   You can print out the buffer with the highlighting that appears
189 on your screen using the command @code{ps-print-buffer-with-faces}.
190 @xref{PostScript}.
192 @node Font Lock
193 @section Font Lock mode
194 @cindex Font Lock mode
195 @cindex mode, Font Lock
196 @cindex syntax highlighting and coloring
198   Font Lock mode is a minor mode, always local to a particular buffer,
199 which highlights (or ``fontifies'') the buffer contents according to
200 the syntax of the text you are editing.  It can recognize comments and
201 strings in most languages; in several languages, it can also recognize
202 and properly highlight various other important constructs---for
203 example, names of functions being defined or reserved keywords.
204 Some special modes, such as Occur mode and Info mode, have completely
205 specialized ways of assigning fonts for Font Lock mode.
207 @findex font-lock-mode
208 @findex turn-on-font-lock
209   The command @kbd{M-x font-lock-mode} turns Font Lock mode on or off
210 according to the argument, and toggles the mode when it has no argument.
211 The function @code{turn-on-font-lock} unconditionally enables Font Lock
212 mode.  This is useful in mode-hook functions.  For example, to enable
213 Font Lock mode whenever you edit a C file, you can do this:
215 @example
216 (add-hook 'c-mode-hook 'turn-on-font-lock)
217 @end example
219 @findex global-font-lock-mode
220 @vindex global-font-lock-mode
221   To turn on Font Lock mode automatically in all modes which support
222 it, customize the variable @code{global-font-lock-mode} or use the
223 function @code{global-font-lock-mode} in your @file{.emacs} file, like
224 this:
226 @example
227 (global-font-lock-mode 1)
228 @end example
230 @noindent
231 You can also specify this using the menu bar Options menu, specifying
232 first Syntax Highlighting and then Save Options.
234   Font Lock mode uses several specifically named faces to do its job,
235 including @code{font-lock-string-face}, @code{font-lock-comment-face},
236 and others.  The easiest way to find them all is to use completion
237 on the face name in @code{set-face-foreground}.
239   To change the colors or the fonts used by Font Lock mode to fontify
240 different parts of text, just change these faces.  There are
241 two ways to do it:
243 @itemize @bullet
244 @item
245 Invoke @kbd{M-x set-face-foreground} or @kbd{M-x set-face-background}
246 to change the colors of a particular face used by Font Lock.
247 @xref{Faces}.  The command @kbd{M-x list-faces-display} displays all
248 the faces currently known to Emacs, including those used by Font Lock.
250 @item
251 Customize the faces interactively with @kbd{M-x customize-face}, as
252 described in @ref{Face Customization}.
253 @end itemize
255 @vindex font-lock-maximum-decoration
256   The variable @code{font-lock-maximum-decoration} specifies the
257 preferred level of fontification, for modes that provide multiple
258 levels.  Level 1 is the least amount of fontification; some modes
259 support levels as high as 3.  The normal default is ``as high as
260 possible.''  You can specify an integer, which applies to all modes, or
261 you can specify different numbers for particular major modes; for
262 example, to use level 1 for C/C++ modes, and the default level
263 otherwise, use this:
265 @example
266 (setq font-lock-maximum-decoration
267       '((c-mode . 1) (c++-mode . 1)))
268 @end example
270 @vindex font-lock-maximum-size
271   Fontification can be too slow for large buffers, so you can suppress
272 it.  The variable @code{font-lock-maximum-size} specifies a buffer size,
273 beyond which buffer fontification is suppressed.
275 @c @w is used below to prevent a bad page-break.
276 @vindex font-lock-beginning-of-syntax-function
277 @cindex incorrect fontification
278 @cindex parenthesis in column zero and fontification
279 @cindex brace in column zero and fontification
280   Comment and string fontification (or ``syntactic'' fontification)
281 relies on analysis of the syntactic structure of the buffer text.  For
282 the sake of speed, some modes, including C mode and Lisp mode,
283 rely on a special convention: an open-parenthesis or open-brace in the
284 leftmost column always defines the @w{beginning} of a defun, and is
285 thus always outside any string or comment.  (@xref{Left Margin
286 Paren}.)  If you don't follow this convention, Font Lock mode can
287 misfontify the text that follows an open-parenthesis or open-brace in
288 the leftmost column that is inside a string or comment.
290 @cindex slow display during scrolling
291   The variable @code{font-lock-beginning-of-syntax-function} (always
292 buffer-local) specifies how Font Lock mode can find a position
293 guaranteed to be outside any comment or string.  In modes which use the
294 leftmost column parenthesis convention, the default value of the variable
295 is @code{beginning-of-defun}---that tells Font Lock mode to use the
296 convention.  If you set this variable to @code{nil}, Font Lock no longer
297 relies on the convention.  This avoids incorrect results, but the price
298 is that, in some cases, fontification for a changed text must rescan
299 buffer text from the beginning of the buffer.  This can considerably
300 slow down redisplay while scrolling, particularly if you are close to
301 the end of a large buffer.
303 @findex font-lock-add-keywords
304   Font Lock highlighting patterns already exist for many modes, but you
305 may want to fontify additional patterns.  You can use the function
306 @code{font-lock-add-keywords}, to add your own highlighting patterns for
307 a particular mode.  For example, to highlight @samp{FIXME:} words in C
308 comments, use this:
310 @example
311 (font-lock-add-keywords
312  'c-mode
313  '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
314 @end example
316 @findex font-lock-remove-keywords
317   To remove keywords from the font-lock highlighting patterns, use the
318 function @code{font-lock-remove-keywords}.  @xref{Search-based
319 Fontification,,, elisp, The Emacs Lisp Reference Manual}, for
320 documentation of the format of this list.
322 @cindex just-in-time (JIT) font-lock
323 @cindex background syntax highlighting
324   Fontifying large buffers can take a long time.  To avoid large
325 delays when a file is visited, Emacs fontifies only the visible
326 portion of a buffer.  As you scroll through the buffer, each portion
327 that becomes visible is fontified as soon as it is displayed.  The
328 parts of the buffer that are not displayed are fontified
329 ``stealthily'', in the background, i.e.@: when Emacs is idle.  You can
330 control this background fontification, also called @dfn{Just-In-Time}
331 (or @dfn{JIT}) Lock, by customizing variables in the customization
332 group @samp{jit-lock}.  @xref{Specific Customization}.
334 @node Highlight Changes
335 @section Highlight Changes Mode
337 @findex highlight-changes-mode
338   Use @kbd{M-x highlight-changes-mode} to enable a minor mode
339 that uses faces (colors, typically) to indicate which parts of
340 the buffer were changed most recently.
342 @node Highlight Interactively
343 @section Interactive Highlighting by Matching
344 @cindex highlighting by matching
345 @cindex interactive highlighting
347   It is sometimes useful to highlight the strings that match a certain
348 regular expression.  For example, you might wish to see all the
349 references to a certain variable in a program source file, or highlight
350 certain parts in a voluminous output of some program, or make certain
351 cliches stand out in an article.
353 @findex hi-lock-mode
354   Use the @kbd{M-x hi-lock-mode} command to turn on a minor mode that
355 allows you to specify regular expressions of the text to be
356 highlighted.  Hi-lock mode works like Font Lock (@pxref{Font Lock}),
357 except that it lets you specify explicitly what parts of text to
358 highlight.  You control Hi-lock mode with these commands:
360 @table @kbd
361 @item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
362 @kindex C-x w h
363 @findex highlight-regexp
364 Highlight text that matches
365 @var{regexp} using face @var{face} (@code{highlight-regexp}).
366 By using this command more than once, you can highlight various
367 parts of the text in different ways.
369 @item C-x w r @var{regexp} @key{RET}
370 @kindex C-x w r
371 @findex unhighlight-regexp
372 Unhighlight @var{regexp} (@code{unhighlight-regexp}).  You must enter
373 one of the regular expressions currently specified for highlighting.
374 (You can use completion, or choose from a menu, to enter one of them
375 conveniently.)
377 @item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
378 @kindex C-x w l
379 @findex highlight-lines-matching-regexp
380 @cindex lines, highlighting
381 @cindex highlighting lines of text
382 Highlight entire lines containing a match for @var{regexp}, using face
383 @var{face} (@code{highlight-lines-matching-regexp}).
385 @item C-x w b
386 @kindex C-x w b
387 @findex hi-lock-write-interactive-patterns
388 Insert all the current highlighting regexp/face pairs into the buffer
389 at point, with comment delimiters to prevent them from changing your
390 program.  This key binding runs the
391 @code{hi-lock-write-interactive-patterns} command.
393 These patterns will be read the next time you visit the file while
394 Hi-lock mode is enabled, or whenever you use the @kbd{M-x
395 hi-lock-find-patterns} command.
397 @item C-x w i
398 @kindex C-x w i
399 @findex hi-lock-find-patterns
400 @vindex hi-lock-exclude-modes
401 Re-read regexp/face pairs in the current buffer
402 (@code{hi-lock-write-interactive-patterns}).  The list of pairs is
403 found no matter where in the buffer it may be.
405 This command does nothing if the major mode is a member of the list
406 @code{hi-lock-exclude-modes}.
407 @end table
409 @node Scrolling
410 @section Scrolling
412   If a buffer contains text that is too large to fit entirely within a
413 window that is displaying the buffer, Emacs shows a contiguous portion of
414 the text.  The portion shown always contains point.
416 @cindex scrolling
417   @dfn{Scrolling} means moving text up or down in the window so that
418 different parts of the text are visible.  Scrolling forward means that text
419 moves up, and new text appears at the bottom.  Scrolling backward moves
420 text down and new text appears at the top.
422   Scrolling happens automatically if you move point past the bottom or top
423 of the window.  You can also explicitly request scrolling with the commands
424 in this section.
426 @table @kbd
427 @item C-l
428 Clear screen and redisplay, scrolling the selected window to center
429 point vertically within it (@code{recenter}).
430 @item C-v
431 Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
432 @item @key{NEXT}
433 @itemx @key{PAGEDOWN}
434 Likewise, scroll forward.
435 @item M-v
436 Scroll backward (@code{scroll-down}).
437 @item @key{PRIOR}
438 @itemx @key{PAGEUP}
439 Likewise, scroll backward.
440 @item @var{arg} C-l
441 Scroll so point is on line @var{arg} (@code{recenter}).
442 @item C-M-l
443 Scroll heuristically to bring useful information onto the screen
444 (@code{reposition-window}).
445 @end table
447 @kindex C-l
448 @findex recenter
449   The most basic scrolling command is @kbd{C-l} (@code{recenter}) with
450 no argument.  It scrolls the selected window so that point is halfway
451 down from the top of the window.  On a text terminal, it also clears
452 the screen and redisplays all windows.  That is useful in case the
453 screen is garbled (@pxref{Screen Garbled}).
455 @kindex C-v
456 @kindex M-v
457 @kindex NEXT
458 @kindex PRIOR
459 @kindex PAGEDOWN
460 @kindex PAGEUP
461 @findex scroll-up
462 @findex scroll-down
463 @vindex next-screen-context-lines
464   To read the buffer a windowful at a time, use @kbd{C-v}
465 (@code{scroll-up}) with no argument.  This scrolls forward by nearly
466 the whole window height.  The effect is to take the two lines at the
467 bottom of the window and put them at the top, followed by nearly a
468 whole windowful of lines that were not previously visible.  If point
469 was in the text that scrolled off the top, it ends up at the new top
470 of the window.
472   @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in
473 a similar way, also with overlap.  The number of lines of overlap
474 across a @kbd{C-v} or @kbd{M-v} is controlled by the variable
475 @code{next-screen-context-lines}; by default, it is 2.  The function
476 keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and @key{PAGEUP},
477 are equivalent to @kbd{C-v} and @kbd{M-v}.
479   The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll
480 the text in the selected window up or down a few lines.  @kbd{C-v}
481 with an argument moves the text and point up, together, that many
482 lines; it brings the same number of new lines into view at the bottom
483 of the window.  @kbd{M-v} with numeric argument scrolls the text
484 downward, bringing that many new lines into view at the top of the
485 window.  @kbd{C-v} with a negative argument is like @kbd{M-v} and vice
486 versa.
488   The names of scroll commands are based on the direction that the
489 text moves in the window.  Thus, the command to scroll forward is
490 called @code{scroll-up} because it moves the text upward on the
491 screen.  The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names
492 and customary meanings from a different convention that developed
493 elsewhere; hence the strange result that @key{PAGEDOWN} runs
494 @code{scroll-up}.
496 @vindex scroll-preserve-screen-position
497   Some users like the full-screen scroll commands to keep point at the
498 same screen line.  To enable this behavior, set the variable
499 @code{scroll-preserve-screen-position} to a non-@code{nil} value.  In
500 this mode, when scrolling shifts point off the screen, or into the
501 scrolling margins, Emacs moves point to keep the same vertical
502 position within the window.  This mode is convenient for browsing
503 through a file by scrolling by screenfuls; if you come back to the
504 screen where you started, point goes back to the line where it
505 started.  However, this mode is inconvenient when you move to the next
506 screen in order to move point to the text there.
508   Another way to do scrolling is with @kbd{C-l} with a numeric argument.
509 @kbd{C-l} does not clear the screen when given an argument; it only scrolls
510 the selected window.  With a positive argument @var{n}, it repositions text
511 to put point @var{n} lines down from the top.  An argument of zero puts
512 point on the very top line.  Point does not move with respect to the text;
513 rather, the text and point move rigidly on the screen.  @kbd{C-l} with a
514 negative argument puts point that many lines from the bottom of the window.
515 For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
516 - 5 C-l} puts it five lines from the bottom.  @kbd{C-u C-l} scrolls to put
517 point at the center (vertically) of the selected window.
519 @kindex C-M-l
520 @findex reposition-window
521   The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
522 window heuristically in a way designed to get useful information onto
523 the screen.  For example, in a Lisp file, this command tries to get the
524 entire current defun onto the screen if possible.
526 @vindex scroll-conservatively
527   Scrolling happens automatically when point moves out of the visible
528 portion of the text.  Normally, automatic scrolling centers point
529 vertically within the window.  However, if you set
530 @code{scroll-conservatively} to a small number @var{n}, then if you
531 move point just a little off the screen---less than @var{n}
532 lines---then Emacs scrolls the text just far enough to bring point
533 back on screen.  By default, @code{scroll-conservatively} is 0.
535 @cindex aggressive scrolling
536 @vindex scroll-up-aggressively
537 @vindex scroll-down-aggressively
538   When the window does scroll by a longer distance, you can control
539 how aggressively it scrolls, by setting the variables
540 @code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
541 The value of @code{scroll-up-aggressively} should be either
542 @code{nil}, or a fraction @var{f} between 0 and 1.  A fraction
543 specifies where on the screen to put point when scrolling upward.
544 More precisely, when a window scrolls up because point is above the
545 window start, the new start position is chosen to put point @var{f}
546 part of the window height from the top.  The larger @var{f}, the more
547 aggressive the scrolling.
549   @code{nil}, which is the default, scrolls to put point at the center.
550 So it is equivalent to .5.
552   Likewise, @code{scroll-down-aggressively} is used for scrolling
553 down.  The value, @var{f}, specifies how far point should be placed
554 from the bottom of the window; thus, as with
555 @code{scroll-up-aggressively}, a larger value is more aggressive.
557 @vindex scroll-margin
558   The variable @code{scroll-margin} restricts how close point can come
559 to the top or bottom of a window.  Its value is a number of screen
560 lines; if point comes within that many lines of the top or bottom of the
561 window, Emacs recenters the window.  By default, @code{scroll-margin} is
564 @node Horizontal Scrolling
565 @section Horizontal Scrolling
566 @cindex horizontal scrolling
568   @dfn{Horizontal scrolling} means shifting all the lines sideways
569 within a window---so that some of the text near the left margin is not
570 displayed at all.  When the text in a window is scrolled horizontally,
571 text lines are truncated rather than continued (@pxref{Display
572 Custom}).  Whenever a window shows truncated lines, Emacs
573 automatically updates its horizontal scrolling whenever point moves
574 off the left or right edge of the screen.  You can also use these
575 commands to do explicit horizontal scrolling.
577 @table @kbd
578 @item C-x <
579 Scroll text in current window to the left (@code{scroll-left}).
580 @item C-x >
581 Scroll to the right (@code{scroll-right}).
582 @end table
584 @kindex C-x <
585 @kindex C-x >
586 @findex scroll-left
587 @findex scroll-right
588   The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected
589 window to the left by @var{n} columns with argument @var{n}.  This moves
590 part of the beginning of each line off the left edge of the window.
591 With no argument, it scrolls by almost the full width of the window (two
592 columns less, to be precise).
594   @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.  The
595 window cannot be scrolled any farther to the right once it is displayed
596 normally (with each line starting at the window's left margin);
597 attempting to do so has no effect.  This means that you don't have to
598 calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large
599 argument will restore the normal display.
601   If you use those commands to scroll a window horizontally, that sets
602 a lower bound for automatic horizontal scrolling.  Automatic scrolling
603 will continue to scroll the window, but never farther to the right
604 than the amount you previously set by @code{scroll-left}.
606 @vindex hscroll-margin
607   The value of the variable @code{hscroll-margin} controls how close
608 to the window's edges point is allowed to get before the window will
609 be automatically scrolled.  It is measured in columns.  If the value
610 is 5, then moving point within 5 columns of the edge causes horizontal
611 scrolling away from that edge.
613 @vindex hscroll-step
614   The variable @code{hscroll-step} determines how many columns to
615 scroll the window when point gets too close to the edge.  If it's
616 zero, horizontal scrolling centers point horizontally within the
617 window.  If it's a positive integer, it specifies the number of
618 columns to scroll by.  If it's a floating-point number, it specifies
619 the fraction of the window's width to scroll by.  The default is zero.
621 @vindex auto-hscroll-mode
622   To disable automatic horizontal scrolling, set the variable
623 @code{auto-hscroll-mode} to @code{nil}.
625 @node Fringes
626 @section Window Fringes
627 @cindex fringes
629   On a graphical display, each Emacs window normally has narrow
630 @dfn{fringes} on the left and right edges.  The fringes display
631 indications about the text in the window.
633   The most common use of the fringes is to indicate a continuation
634 line, when one line of text is split into multiple lines on the
635 screen.  The left fringe shows a curving arrow for each screen line
636 except the first, indicating that ``this is not the real beginning.''
637 The right fringe shows a curving arrow for each screen line except the
638 last, indicating that ``this is not the real end.''
640   The fringes indicate line truncation with short horizontal arrows
641 meaning ``there's more text on this line which is scrolled
642 horizontally out of view;'' clicking the mouse on one of the arrows
643 scrolls the display horizontally in the direction of the arrow.   The
644 fringes also indicate other things such as empty lines, or where a
645 program you are debugging is executing (@pxref{Debuggers}).
647 @findex set-fringe-style
648 @findex fringe-mode
649   You can enable and disable the fringes for all frames using
650 @kbd{M-x fringe-mode}.  To enable and disable the fringes
651 for the selected frame, use @kbd{M-x set-fringe-style}.
653 @node Useless Whitespace
654 @section Useless Whitespace
656 @cindex trailing whitespace
657 @cindex whitespace, trailing
658 @vindex show-trailing-whitespace
659   It is easy to leave unnecessary spaces at the end of a line, or
660 empty lines at the end of a file, without realizing it.  In most
661 cases, this @dfn{trailing whitespace} has no effect, but there are
662 special circumstances where it matters.
664   You can make trailing whitespace at the end of a line visible on the
665 screen by setting the buffer-local variable
666 @code{show-trailing-whitespace} to @code{t}.  Then Emacs displays
667 trailing whitespace in the face @code{trailing-whitespace}.
669   This feature does not apply when point is at the end of the line
670 containing the whitespace.  Strictly speaking, that is ``trailing
671 whitespace'' nonetheless, but displaying it specially in that case
672 looks ugly while you are typing in new text.  In this special case,
673 the location of point is enough to show you that the spaces are
674 present.
676 @findex delete-trailing-whitespace
677   To delete all trailing whitespace within the current buffer's
678 accessible portion (@pxref{Narrowing}), type @kbd{M-x
679 delete-trailing-whitespace @key{RET}}.  (This command does not remove
680 the form-feed characters.)
682 @vindex indicate-unused-lines
683 @vindex default-indicate-empty-lines
684 @cindex unused lines
685 @cindex fringes, and unused line indication
686   Emacs can indicate unused lines at the end of the window with a
687 small image in the left fringe (@pxref{Fringes}).  The image appears
688 for window lines that do not correspond to any buffer text.  Blank
689 lines at the end of the buffer then stand out because they do not have
690 this image in the fringe.
692   To enable this feature, set the buffer-local variable
693 @code{indicate-unused-lines} to a non-@code{nil} value.  The default
694 value of this variable is controlled by the variable
695 @code{default-indicate-unused-lines}; by setting that variable, you
696 can enable or disable this feature for all new buffers.  (This feature
697 currently doesn't work on character terminals.)
699 @node Follow Mode
700 @section Follow Mode
701 @cindex Follow mode
702 @cindex mode, Follow
703 @findex follow-mode
704 @cindex windows, synchronizing
705 @cindex synchronizing windows
707   @dfn{Follow mode} is a minor mode that makes two windows, both
708 showing the same buffer, scroll as a single tall ``virtual window.''
709 To use Follow mode, go to a frame with just one window, split it into
710 two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
711 follow-mode}.  From then on, you can edit the buffer in either of the
712 two windows, or scroll either one; the other window follows it.
714   In Follow mode, if you move point outside the portion visible in one
715 window and into the portion visible in the other window, that selects
716 the other window---again, treating the two as if they were parts of
717 one large window.
719   To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
721 @node Selective Display
722 @section Selective Display
723 @cindex selective display
724 @findex set-selective-display
725 @kindex C-x $
727   Emacs has the ability to hide lines indented more than a certain number
728 of columns (you specify how many columns).  You can use this to get an
729 overview of a part of a program.
731   To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
732 numeric argument @var{n}.  Then lines with at least @var{n} columns of
733 indentation disappear from the screen.  The only indication of their
734 presence is that three dots (@samp{@dots{}}) appear at the end of each
735 visible line that is followed by one or more hidden ones.
737   The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
738 if they were not there.
740   The hidden lines are still present in the buffer, and most editing
741 commands see them as usual, so you may find point in the middle of the
742 hidden text.  When this happens, the cursor appears at the end of the
743 previous line, after the three dots.  If point is at the end of the
744 visible line, before the newline that ends it, the cursor appears before
745 the three dots.
747   To make all lines visible again, type @kbd{C-x $} with no argument.
749 @vindex selective-display-ellipses
750   If you set the variable @code{selective-display-ellipses} to
751 @code{nil}, the three dots do not appear at the end of a line that
752 precedes hidden lines.  Then there is no visible indication of the
753 hidden lines.  This variable becomes local automatically when set.
755   See also @ref{Outline Mode} for another way to hide part of
756 the text in a buffer.
758 @node Optional Mode Line
759 @section Optional Mode Line Features
761 @cindex buffer size display
762 @cindex display of buffer size
763 @findex size-indication-mode
764   The buffer percentage @var{pos} indicates the percentage of the
765 buffer above the top of the window.  You can additionally display the
766 size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
767 Size Indication mode.  The size will be displayed immediately
768 following the buffer percentage like this:
770 @example
771 @var{POS} of @var{SIZE}
772 @end example
774 @noindent
775 Here @var{SIZE} is the human readable representation of the number of
776 characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
777 for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
779 @cindex narrowing, and buffer size display
780   If you have narrowed the buffer (@pxref{Narrowing}), the size of the
781 accessible part of the buffer is shown.
783 @cindex line number display
784 @cindex display of line number
785 @findex line-number-mode
786   The current line number of point appears in the mode line when Line
787 Number mode is enabled.  Use the command @kbd{M-x line-number-mode} to
788 turn this mode on and off; normally it is on.  The line number appears
789 after the buffer percentage @var{pos}, with the letter @samp{L} to
790 indicate what it is.  @xref{Minor Modes}, for more information about
791 minor modes and about how to use this command.
793 @cindex narrowing, and line number display
794   If you have narrowed the buffer (@pxref{Narrowing}), the displayed
795 line number is relative to the accessible portion of the buffer.
797 @vindex line-number-display-limit
798   If the buffer is very large (larger than the value of
799 @code{line-number-display-limit}), then the line number doesn't appear.
800 Emacs doesn't compute the line number when the buffer is large, because
801 that would be too slow.  Set it to @code{nil} to remove the limit.
803 @vindex line-number-display-limit-width
804   Line-number computation can also be slow if the lines in the buffer
805 are too long.  For this reason, Emacs normally doesn't display line
806 numbers if the average width, in characters, of lines near point is
807 larger than the value of the variable
808 @code{line-number-display-limit-width}.  The default value is 200
809 characters.
811 @cindex Column Number mode
812 @cindex mode, Column Number
813 @findex column-number-mode
814   You can also display the current column number by turning on Column
815 Number mode.  It displays the current column number preceded by the
816 letter @samp{C}.  Type @kbd{M-x column-number-mode} to toggle this mode.
818 @findex display-time
819 @cindex time (on mode line)
820   Emacs can optionally display the time and system load in all mode
821 lines.  To enable this feature, type @kbd{M-x display-time} or customize
822 the option @code{display-time-mode}.  The information added to the mode
823 line usually appears after the buffer name, before the mode names and
824 their parentheses.  It looks like this:
826 @example
827 @var{hh}:@var{mm}pm @var{l.ll}
828 @end example
830 @noindent
831 @vindex display-time-24hr-format
832 Here @var{hh} and @var{mm} are the hour and minute, followed always by
833 @samp{am} or @samp{pm}.  @var{l.ll} is the average number of running
834 processes in the whole system recently.  (Some fields may be missing if
835 your operating system cannot support them.)  If you prefer time display
836 in 24-hour format, set the variable @code{display-time-24hr-format}
837 to @code{t}.
839 @cindex mail (on mode line)
840 @vindex display-time-use-mail-icon
841 @vindex display-time-mail-face
842 @vindex display-time-mail-file
843 @vindex display-time-mail-directory
844   The word @samp{Mail} appears after the load level if there is mail
845 for you that you have not read yet.  On a graphical display you can use
846 an icon instead of @samp{Mail} by customizing
847 @code{display-time-use-mail-icon}; this may save some space on the mode
848 line.  You can customize @code{display-time-mail-face} to make the mail
849 indicator prominent.  Use @code{display-time-mail-file} to specify
850 the mail file to check, or set @code{display-time-mail-directory}
851 to specify the directory to check for incoming mail (any nonempty regular
852 file in the directory is considered as ``newly arrived mail'').
854 @cindex mode line, 3D appearance
855 @cindex attributes of mode line, changing
856 @cindex non-integral number of lines in a window
857   By default, the mode line is drawn on graphics displays with
858 3D-style highlighting, like that of a button when it is not being
859 pressed.  If you don't like this effect, you can disable the 3D
860 highlighting of the mode line, by customizing the attributes of the
861 @code{mode-line} face in your @file{.emacs} init file, like this:
863 @example
864 (set-face-attribute 'mode-line nil :box nil)
865 @end example
867 @noindent
868 Alternatively, you can turn off the box attribute in your
869 @file{.Xdefaults} file:
871 @example
872 Emacs.mode-line.AttributeBox: off
873 @end example
875 @cindex non-selected windows, mode line appearance
876   By default, the mode line of nonselected windows is displayed in a
877 different face, called @code{mode-line-inactive}.  Only the selected
878 window is displayed in the @code{mode-line} face.  This helps show
879 which window is selected.  When the minibuffer is selected, since
880 it has no mode line, the window from which you activated the minibuffer
881 has its mode line displayed using @code{mode-line}; as a result,
882 ordinary entry to the minibuffer does not change any mode lines.
884 @vindex mode-line-in-non-selected-windows
885   You can disable use of @code{mode-line-inactive} by setting variable
886 @code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
887 lines are displayed in the @code{mode-line} face.
889 @node Text Display
890 @section How Text Is Displayed
891 @cindex characters (in text)
893   @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs
894 buffers are displayed with their graphics, as are non-ASCII multibyte
895 printing characters (octal codes above 0400).
897   Some @acronym{ASCII} control characters are displayed in special ways.  The
898 newline character (octal code 012) is displayed by starting a new line.
899 The tab character (octal code 011) is displayed by moving to the next
900 tab stop column (normally every 8 columns).
902   Other @acronym{ASCII} control characters are normally displayed as a caret
903 (@samp{^}) followed by the non-control version of the character; thus,
904 control-A is displayed as @samp{^A}.
906   Non-@acronym{ASCII} characters 0200 through 0237 (octal) are displayed with
907 octal escape sequences; thus, character code 0230 (octal) is displayed
908 as @samp{\230}.  The display of character codes 0240 through 0377
909 (octal) may be either as escape sequences or as graphics.  They do not
910 normally occur in multibyte buffers, but if they do, they are displayed
911 as Latin-1 graphics.  In unibyte mode, if you enable European display
912 they are displayed using their graphics (assuming your terminal supports
913 them), otherwise as escape sequences.  @xref{Single-Byte Character
914 Support}.
916 @node Cursor Display
917 @section Displaying the Cursor
919 @findex blink-cursor-mode
920 @vindex blink-cursor-alist
921 @cindex cursor, locating visually
922 @cindex cursor, blinking
923   You can customize the cursor's color, and whether it blinks, using
924 the @code{cursor} Custom group (@pxref{Easy Customization}).  On
925 graphical terminals, the command @kbd{M-x blink-cursor-mode} enables
926 or disables the blinking of the cursor.  (On text terminals, the
927 terminal itself blinks the cursor, and Emacs has no control over it.)
928 You can control how the cursor appears when it blinks off by setting
929 the variable @code{blink-cursor-alist}.
931 @cindex cursor in non-selected windows
932 @vindex cursor-in-non-selected-windows
933   Normally, the cursor appears in non-selected windows in the ``off''
934 state, with the same appearance as when the blinking cursor blinks
935 ``off''.  For a box cursor, this is a hollow box; for a bar cursor,
936 this is a thinner bar.  To turn off cursors in non-selected windows,
937 customize the variable @code{cursor-in-non-selected-windows} and assign
938 it a @code{nil} value.
940 @vindex x-stretch-cursor
941 @cindex wide block cursor
942   On graphical terminals, Emacs can optionally draw the block cursor
943 as wide as the character under the cursor---for example, if the cursor
944 is on a tab character, it would cover the full width occupied by that
945 tab character.  To enable this feature, set the variable
946 @code{x-stretch-cursor} to a non-@code{nil} value.
948 @findex hl-line-mode
949 @findex global-hl-line-mode
950 @cindex highlight current line
951   If you find it hard to see the cursor, you might like HL Line mode,
952 a minor mode that highlights the line containing point.  Use @kbd{M-x
953 hl-line-mode} to enable or disable it in the current buffer.  @kbd{M-x
954 global-hl-line-mode} enables or disables the same mode globally.
956 @node Display Custom
957 @section Customization of Display
959   This section contains information for customization only.  Beginning
960 users should skip it.
962 @vindex mode-line-inverse-video
963   The variable @code{mode-line-inverse-video} is an obsolete way of
964 controlling whether the mode line is displayed in inverse video; the
965 preferred way of doing this is to change the @code{mode-line} face.
966 @xref{Mode Line}.  However, if @code{mode-line-inverse-video} has a
967 value of @code{nil}, then the @code{mode-line} face will be ignored,
968 and mode-lines will be drawn using the default text face.
969 @xref{Faces}.
971 @vindex inverse-video
972   If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
973 to invert all the lines of the display from what they normally are.
975 @vindex visible-bell
976   If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
977 to make the whole screen blink when it would normally make an audible bell
978 sound.  This variable has no effect if your terminal does not have a way
979 to make the screen blink.
981 @vindex no-redraw-on-reenter
982   On a text terminal, when you reenter Emacs after suspending, Emacs
983 normally clears the screen and redraws the entire display.  On some
984 terminals with more than one page of memory, it is possible to arrange
985 the termcap entry so that the @samp{ti} and @samp{te} strings (output
986 to the terminal when Emacs is entered and exited, respectively) switch
987 between pages of memory so as to use one page for Emacs and another
988 page for other output.  Then you might want to set the variable
989 @code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to
990 assume, when resumed, that the screen page it is using still contains
991 what Emacs last wrote there.
993 @vindex echo-keystrokes
994   The variable @code{echo-keystrokes} controls the echoing of multi-character
995 keys; its value is the number of seconds of pause required to cause echoing
996 to start, or zero meaning don't echo at all.  @xref{Echo Area}.
998 @vindex ctl-arrow
999   If the variable @code{ctl-arrow} is @code{nil}, all control characters in
1000 the buffer are displayed with octal escape sequences, except for newline
1001 and tab.  Altering the value of @code{ctl-arrow} makes it local to the
1002 current buffer; until that time, the default value is in effect.  The
1003 default is initially @code{t}.  @xref{Display Tables,, Display Tables,
1004 elisp, The Emacs Lisp Reference Manual}.
1006 @vindex tab-width
1007 @vindex default-tab-width
1008   Normally, a tab character in the buffer is displayed as whitespace which
1009 extends to the next display tab stop position, and display tab stops come
1010 at intervals equal to eight spaces.  The number of spaces per tab is
1011 controlled by the variable @code{tab-width}, which is made local by
1012 changing it, just like @code{ctl-arrow}.  Note that how the tab character
1013 in the buffer is displayed has nothing to do with the definition of
1014 @key{TAB} as a command.  The variable @code{tab-width} must have an
1015 integer value between 1 and 1000, inclusive.  The variable
1016 @code{default-tab-width} controls the default value of this variable
1017 for buffers where you have not set it locally.
1019 @cindex truncation
1020 @cindex line truncation, and fringes
1021   As an alternative to continuation, Emacs can display long lines by
1022 @dfn{truncation}.  This means that all the characters that do not fit
1023 in the width of the screen or window do not appear at all.  On
1024 graphical terminals, a small straight arrow in the fringe indicates
1025 truncation at either end of the line.  On text terminals, @samp{$}
1026 appears in the first column when there is text truncated to the left,
1027 and in the last column when there is text truncated to the right.
1029 @vindex truncate-lines
1030 @findex toggle-truncate-lines
1031   Horizontal scrolling automatically causes line truncation
1032 (@pxref{Horizontal Scrolling}).  You can explicitly enable line
1033 truncation for a particular buffer with the command @kbd{M-x
1034 toggle-truncate-lines}.  This works by locally changing the variable
1035 @code{truncate-lines}.  If that variable is non-@code{nil}, long lines
1036 are truncated; if it is @code{nil}, they are continued onto multiple
1037 screen lines.  Setting the variable @code{truncate-lines} in any way
1038 makes it local to the current buffer; until that time, the default
1039 value is in effect.  The default value is normally @code{nil}.
1041 @c @vindex truncate-partial-width-windows  @c Idx entry is in Split Windows.
1042   If the variable @code{truncate-partial-width-windows} is
1043 non-@code{nil}, it forces truncation rather than continuation in any
1044 window less than the full width of the screen or frame, regardless of
1045 the value of @code{truncate-lines}.  For information about side-by-side
1046 windows, see @ref{Split Window}.  See also @ref{Display,, Display,
1047 elisp, The Emacs Lisp Reference Manual}.
1049 @vindex overflow-newline-into-fringe
1050   If the variable @code{overflow-newline-into-fringe} is
1051 non-@code{nil} on a window system, it specifies that lines which are
1052 exactly as wide as the window (not counting the final newline
1053 character) shall not be broken into two lines on the display (with
1054 just the newline on the second line).  Instead, the newline
1055 overflows into the right fringe, and the cursor will be displayed in
1056 the fringe when positioned on that newline.
1058 @vindex indicate-buffer-boundaries
1059   On a window system, Emacs may indicate the buffer boundaries in the
1060 fringes.  The buffer boundaries, i.e. first and last line in the
1061 buffer, can be marked with angle bitmaps in the left or right fringe.
1062 This can be combined with up and down arrow bitmaps shown at the top
1063 and bottom of the left or right fringe if the window can be scrolled
1064 in either direction.
1066   The buffer-local variable @code{indicate-buffer-boundaries} controls
1067 how the buffer boundaries and window scrolling is indicated in the
1068 fringes.
1070   If the value is @code{left} or @code{right}, both angle and arrow
1071 bitmaps are displayed in the left or right fringe, respectively.
1073   If value is an alist, each element @code{(@var{indicator} .
1074 @var{position})} specifies the position of one of the indicators.
1075 The @var{indicator} must be one of @code{top}, @code{bottom},
1076 @code{up}, @code{down}, or @code{t} which specifies the default
1077 position for the indicators not present in the alist.
1078 The @var{position} is one of @code{left}, @code{right}, or @code{ni}
1079 which specifies not to show this indicator.
1081   For example, @code{((top . left) (t . right))} places the top angle
1082 bitmap in left fringe, the bottom angle bitmap in right fringe, and
1083 both arrow bitmaps in right fringe.  To show just the angle bitmaps in
1084 the left fringe, but no arrow bitmaps, use @code{((top .  left)
1085 (bottom . left))}.
1087 @vindex default-indicate-buffer-boundaries
1088   The value of the variable @code{default-indicate-buffer-boundaries}
1089 is the default value for @code{indicate-buffer-boundaries} in buffers
1090 that do not override it.
1092 @vindex baud-rate
1093   The variable @code{baud-rate} holds the output speed of the
1094 terminal, as far as Emacs knows.  Setting this variable does not
1095 change the speed of actual data transmission, but the value is used
1096 for calculations.  On terminals, it affects padding, and decisions
1097 about whether to scroll part of the screen or redraw it instead.
1098 It also affects the behavior of incremental search.
1100   On window-systems, @code{baud-rate} is only used to determine how
1101 frequently to look for pending input during display updating.  A
1102 higher value of @code{baud-rate} means that check for pending input
1103 will be done less frequently.
1105   You can customize the way any particular character code is displayed
1106 by means of a display table.  @xref{Display Tables,, Display Tables,
1107 elisp, The Emacs Lisp Reference Manual}.
1109 @cindex hourglass pointer display
1110 @vindex hourglass-delay
1111   On a window system, Emacs can optionally display the mouse pointer
1112 in a special shape to say that Emacs is busy.  To turn this feature on
1113 or off, customize the group @code{cursor}.  You can also control the
1114 amount of time Emacs must remain busy before the busy indicator is
1115 displayed, by setting the variable @code{hourglass-delay}.
1117 @findex tty-suppress-bold-inverse-default-colors
1118   On some text-only terminals, bold face and inverse video together
1119 result in text that is hard to read.  Call the function
1120 @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
1121 argument to suppress the effect of bold-face in this case.
1123 @ignore
1124    arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4
1125 @end ignore