0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
0004: @c Foundation, Inc.
0005: 
0006: @c See file emacs.texi for copying conditions.
0007: @node Display
0008: @chapter Controlling the Display
0009: 
0010:   Since only part of a large buffer fits in the window, Emacs has to
0011: show only a part of it.  This chapter describes commands and variables
0012: that let you specify which part of the text you want to see, and how
0013: the text is displayed.
0014: 
0015: @menu
0016: * Scrolling::              Commands to move text up and down in a window.
0017: * Recentering::            A scroll command that centers the current line.
0018: * Auto Scrolling::         Redisplay scrolls text automatically when needed.
0019: * Horizontal Scrolling::   Moving text left and right in a window.
0020: * Narrowing::              Restricting display and editing to a portion
0021:                              of the buffer.
0022: * View Mode::              Viewing read-only buffers.
0023: * Follow Mode::            Follow mode lets two windows scroll as one.
0024: * Faces::                  How to change the display style using faces.
0025: * Colors::                 Specifying colors for faces.
0026: * Standard Faces::         The main predefined faces.
0027: * Text Scale::             Increasing or decreasing text size in a buffer.
0028: * Font Lock::              Minor mode for syntactic highlighting using faces.
0029: * Highlight Interactively:: Tell Emacs what text to highlight.
0030: * Fringes::                Enabling or disabling window fringes.
0031: * Displaying Boundaries::  Displaying top and bottom of the buffer.
0032: * Useless Whitespace::     Showing possibly spurious trailing whitespace.
0033: * Selective Display::      Hiding lines with lots of indentation.
0034: * Optional Mode Line::     Optional mode line display features.
0035: * Text Display::           How text characters are normally displayed.
0036: * Cursor Display::         Features for displaying the cursor.
0037: * Line Truncation::        Truncating lines to fit the screen width instead
0038:                              of continuing them to multiple screen lines.
0039: * Visual Line Mode::       Word wrap and screen line-based editing.
0040: * Display Custom::         Information on variables for customizing display.
0041: @end menu
0042: 
0043: @node Scrolling
0044: @section Scrolling
0045: @cindex scrolling
0046: 
0047:   If a window is too small to display all the text in its buffer, it
0048: displays only a portion of it.  @dfn{Scrolling} commands change which
0049: portion of the buffer is displayed.
0050: 
0051:   Scrolling forward or up advances the portion of the buffer
0052: displayed in the window; equivalently, it moves the buffer text
0053: upwards relative to the window.  Scrolling backward or down
0054: displays an earlier portion of the buffer, and moves the text
0055: downwards relative to the window.
0056: 
0057:   In Emacs, scrolling up or down refers to the direction that
0058: the text moves in the window, @emph{not} the direction that the window
0059: moves relative to the text.  This terminology was adopted by Emacs
0060: before the modern meaning of ``scrolling up'' and ``scrolling down''
0061: became widespread.  Hence, the strange result that @key{PageDown}
0062: scrolls up in the Emacs sense.
0063: 
0064:   The portion of a buffer displayed in a window always contains point.
0065: If you move point past the bottom or top of the window, scrolling
0066: occurs automatically to bring it back onscreen (@pxref{Auto
0067: Scrolling}).  You can also scroll explicitly with these commands:
0068: 
0069: @table @kbd
0070: @item C-v
0071: @itemx @key{PageDown}
0072: @itemx @key{next}
0073: Scroll forward by nearly a full window (@code{scroll-up-command}).
0074: @item M-v
0075: @itemx @key{PageUp}
0076: @itemx @key{prior}
0077: Scroll backward (@code{scroll-down-command}).
0078: @end table
0079: 
0080: @kindex C-v
0081: @kindex M-v
0082: @kindex PageDown
0083: @kindex PageUp
0084: @kindex next
0085: @kindex prior
0086: @findex scroll-up-command
0087: @findex scroll-down-command
0088:   @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
0089: whole window height.  The effect is to take the two lines at the
0090: bottom of the window and put them at the top, followed by lines that
0091: were not previously visible.  If point was in the text that scrolled
0092: off the top, it ends up on the window's new topmost line.  The
0093: @key{PageDown} (or @key{next}) key is equivalent to @kbd{C-v}.
0094: 
0095:   @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar
0096: way.  The @key{PageUp} (or @key{prior}) key is equivalent to
0097: @kbd{M-v}.
0098: 
0099: @vindex next-screen-context-lines
0100:   The number of lines of overlap left by these scroll commands is
0101: controlled by the variable @code{next-screen-context-lines}, whose
0102: default value is 2.  You can supply the commands with a numeric prefix
0103: argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave
0104: point unchanged, so that the text and point move up or down together.
0105: @kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa.
0106: 
0107: @vindex scroll-error-top-bottom
0108:   By default, these commands signal an error (by beeping or flashing
0109: the screen) if no more scrolling is possible, because the window has
0110: reached the beginning or end of the buffer.  If you change the
0111: variable @code{scroll-error-top-bottom} to @code{t}, these commands
0112: move point to the farthest possible position.  If point is already
0113: there, the commands signal an error.
0114: 
0115: @vindex scroll-preserve-screen-position
0116: @cindex @code{scroll-command} property
0117:   Some users like scroll commands to keep point at the same screen
0118: position, so that scrolling back to the same screen conveniently
0119: returns point to its original position.  You can enable this behavior
0120: via the variable @code{scroll-preserve-screen-position}.  If the value
0121: is @code{t}, Emacs adjusts point to keep the cursor at the same screen
0122: position whenever a scroll command moves it off-window, rather than
0123: moving it to the topmost or bottommost line.  With any other
0124: non-@code{nil} value, Emacs adjusts point this way even if the scroll
0125: command leaves point in the window.  This variable affects all the
0126: scroll commands documented in this section, as well as scrolling with
0127: the mouse wheel (@pxref{Mouse Commands}); in general, it affects any
0128: command that has a non-@code{nil} @code{scroll-command} property.
0129: @xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}.
0130: 
0131: @vindex fast-but-imprecise-scrolling
0132:   Sometimes, particularly when you hold down keys such as @kbd{C-v}
0133: and @kbd{M-v}, activating keyboard auto-repeat, Emacs fails to keep up
0134: with the rapid rate of scrolling requested; the display doesn't update
0135: and Emacs can become unresponsive to input for quite a long time.  You
0136: can counter this sluggishness by setting the variable
0137: @code{fast-but-imprecise-scrolling} to a non-@code{nil} value.  This
0138: instructs the scrolling commands not to fontify (@pxref{Font Lock})
0139: any unfontified text they scroll over, instead to assume it has the
0140: default face.  This can cause Emacs to scroll to somewhat wrong buffer
0141: positions when the faces in use are not all the same size, even with
0142: single (i.e., without auto-repeat) scrolling operations.
0143: 
0144: @vindex scroll-up
0145: @vindex scroll-down
0146: @findex scroll-up-line
0147: @findex scroll-down-line
0148:   The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave
0149: similarly to @code{scroll-up-command} and @code{scroll-down-command},
0150: except they do not obey @code{scroll-error-top-bottom}.  Prior to
0151: Emacs 24, these were the default commands for scrolling up and down.
0152: The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line}
0153: scroll the current window by one line at a time.  If you intend to use
0154: any of these commands, you might want to give them key bindings
0155: (@pxref{Init Rebinding}).
0156: 
0157: @node Recentering
0158: @section Recentering
0159: 
0160: @table @kbd
0161: @item C-l
0162: Scroll the selected window so the current line is the center-most text
0163: line; on subsequent consecutive invocations, make the current line the
0164: top line, the bottom line, and so on in cyclic order.  Possibly
0165: redisplay the screen too (@code{recenter-top-bottom}).
0166: 
0167: @item M-x recenter
0168: Scroll the selected window so the current line is the center-most text
0169: line.  Possibly redisplay the screen too.
0170: 
0171: @item C-M-l
0172: Scroll heuristically to bring useful information onto the screen
0173: (@code{reposition-window}).
0174: @end table
0175: 
0176: @kindex C-l
0177: @findex recenter-top-bottom
0178:   The @kbd{C-l} (@code{recenter-top-bottom}) command @dfn{recenters}
0179: the selected window, scrolling it so that the current screen line is
0180: exactly in the center of the window, or as close to the center as
0181: possible.
0182: 
0183:   Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window
0184: so that point is on the topmost screen line.  Typing a third @kbd{C-l}
0185: scrolls the window so that point is on the bottom-most screen line.
0186: Each successive @kbd{C-l} cycles through these three positions.
0187: 
0188: @vindex recenter-positions
0189:   You can change the cycling order by customizing the list variable
0190: @code{recenter-positions}.  Each list element should be the symbol
0191: @code{top}, @code{middle}, or @code{bottom}, or a number; an integer
0192: means to move the line to the specified screen line, while a
0193: floating-point number between 0.0 and 1.0 specifies a percentage of
0194: the screen space from the top of the window.  The default,
0195: @code{(middle top bottom)}, is the cycling order described above.
0196: Furthermore, if you change the variable @code{scroll-margin} to a
0197: non-zero value @var{n}, @kbd{C-l} always leaves at least @var{n}
0198: screen lines between point and the top or bottom of the window
0199: (@pxref{Auto Scrolling}).
0200: 
0201:   You can also give @kbd{C-l} a prefix argument.  A plain prefix
0202: argument, @kbd{C-u C-l}, simply recenters point.  A positive argument
0203: @var{n} puts point @var{n} lines down from the top of the window.  An
0204: argument of zero puts point on the topmost line.  A negative argument
0205: @var{-n} puts point @var{n} lines from the bottom of the window.  When
0206: given an argument, @kbd{C-l} does not clear the screen or cycle
0207: through different screen positions.
0208: 
0209: @vindex recenter-redisplay
0210:   If the variable @code{recenter-redisplay} has a non-@code{nil}
0211: value, each invocation of @kbd{C-l} also clears and redisplays the
0212: screen; the special value @code{tty} (the default) says to do this on
0213: text-terminal frames only.  Redisplaying is useful in case the screen
0214: becomes garbled for any reason (@pxref{Screen Garbled}).
0215: 
0216: @findex recenter
0217:   The more primitive command @kbd{M-x recenter} behaves like
0218: @code{recenter-top-bottom}, but does not cycle among screen positions.
0219: 
0220: @kindex C-M-l
0221: @findex reposition-window
0222:   @kbd{C-M-l} (@code{reposition-window}) scrolls the current window
0223: heuristically in a way designed to get useful information onto the
0224: screen.  For example, in a Lisp file, this command tries to get the
0225: entire current defun onto the screen if possible.
0226: 
0227: @node Auto Scrolling
0228: @section Automatic Scrolling
0229: 
0230: @cindex automatic scrolling
0231:   Emacs performs @dfn{automatic scrolling} when point moves out of the
0232: visible portion of the text.  Normally, automatic scrolling centers
0233: point vertically in the window, but there are several ways to alter
0234: this behavior.
0235: 
0236: @vindex scroll-conservatively
0237:   If you set @code{scroll-conservatively} to a small number @var{n},
0238: then moving point just a little off the screen (no more than @var{n}
0239: lines) causes Emacs to scroll just enough to bring point back on
0240: screen; if doing so fails to make point visible, Emacs scrolls just
0241: far enough to center point in the window.  If you set
0242: @code{scroll-conservatively} to a large number (larger than 100),
0243: automatic scrolling never centers point, no matter how far point
0244: moves; Emacs always scrolls text just enough to bring point into view,
0245: either at the top or bottom of the window depending on the scroll
0246: direction.  By default, @code{scroll-conservatively} is@tie{}0, which
0247: means to always center point in the window.
0248: 
0249: @vindex scroll-step
0250:   Another way to control automatic scrolling is to customize the
0251: variable @code{scroll-step}.  Its value determines the number of lines
0252: by which to automatically scroll, when point moves off the screen.  If
0253: scrolling by that number of lines fails to bring point back into view,
0254: point is centered instead.  The default value is zero, which (by
0255: default) causes point to always be centered after scrolling.
0256: 
0257: @cindex aggressive scrolling
0258: @vindex scroll-up-aggressively
0259: @vindex scroll-down-aggressively
0260:   A third way to control automatic scrolling is to customize the
0261: variables @code{scroll-up-aggressively} and
0262: @code{scroll-down-aggressively}, which directly specify the vertical
0263: position of point after scrolling.  The value of
0264: @code{scroll-up-aggressively} should be either @code{nil} (the
0265: default), or a floating point number @var{f} between 0 and 1.  The
0266: latter means that when point goes below the bottom window edge (i.e.,
0267: scrolling forward), Emacs scrolls the window so that point is @var{f}
0268: parts of the window height from the bottom window edge.  Thus, larger
0269: @var{f} means more aggressive scrolling: more new text is brought into
0270: view.  The default value, @code{nil}, is equivalent to 0.5.
0271: 
0272:   Likewise, @code{scroll-down-aggressively} is used when point goes
0273: above the top window edge (i.e., scrolling backward).  The value
0274: specifies how far point should be from the top margin of the window
0275: after scrolling.  Thus, as with @code{scroll-up-aggressively}, a
0276: larger value is more aggressive.
0277: 
0278:   Note that the variables @code{scroll-conservatively},
0279: @code{scroll-step}, and @code{scroll-up-aggressively} /
0280: @code{scroll-down-aggressively} control automatic scrolling in
0281: contradictory ways.  Therefore, you should pick no more than one of
0282: these methods to customize automatic scrolling.  In case you customize
0283: multiple variables, the order of priority is:
0284: @code{scroll-conservatively}, then @code{scroll-step}, and finally
0285: @code{scroll-up-aggressively} / @code{scroll-down-aggressively}.
0286: 
0287: @vindex scroll-margin
0288: @vindex maximum-scroll-margin
0289:   The variable @code{scroll-margin} restricts how close point can come
0290: to the top or bottom of a window (even if aggressive scrolling
0291: specifies a fraction @var{f} that is larger than the window portion
0292: between the top and the bottom margins).  Its value is a number of
0293: screen lines; if point comes within that many lines of the top or
0294: bottom of the window, Emacs performs automatic scrolling.  By default,
0295: @code{scroll-margin} is 0.  The effective margin size is limited to a
0296: quarter of the window height by default, but this limit can be
0297: increased up to half (or decreased down to zero) by customizing
0298: @code{maximum-scroll-margin}.
0299: 
0300: @node Horizontal Scrolling
0301: @section Horizontal Scrolling
0302: @cindex horizontal scrolling
0303: 
0304: @vindex auto-hscroll-mode
0305:   @dfn{Horizontal scrolling} means shifting all the lines sideways
0306: within a window, so that some of the text near the left margin is not
0307: displayed.  When the text in a window is scrolled horizontally, text
0308: lines are truncated rather than continued (@pxref{Line Truncation}).
0309: If a window shows truncated lines, Emacs performs automatic horizontal
0310: scrolling whenever point moves off the left or right edge of the
0311: screen.  By default, all the lines in the window are scrolled
0312: horizontally together, but if you set the variable
0313: @code{auto-hscroll-mode} to the special value of @code{current-line},
0314: only the line showing the cursor will be scrolled.  To disable
0315: automatic horizontal scrolling entirely, set the variable
0316: @code{auto-hscroll-mode} to @code{nil}.  Note that when the automatic
0317: horizontal scrolling is turned off, if point moves off the edge of the
0318: screen, the cursor disappears to indicate that.  (On text terminals,
0319: the cursor is left at the edge instead.)
0320: 
0321: @vindex hscroll-margin
0322:   The variable @code{hscroll-margin} controls how close point can get
0323: to the window's left and right edges before automatic scrolling
0324: occurs.  It is measured in columns.  For example, if the value is 5,
0325: then moving point within 5 columns of an edge causes horizontal
0326: scrolling away from that edge.
0327: 
0328: @vindex hscroll-step
0329:   The variable @code{hscroll-step} determines how many columns to
0330: scroll the window when point gets too close to the edge.  Zero, the
0331: default value, means to center point horizontally within the window.
0332: A positive integer value specifies the number of columns to scroll by.
0333: A floating-point number (whose value should be between 0 and 1)
0334: specifies the fraction of the window's width to scroll by.
0335: 
0336:   You can also perform explicit horizontal scrolling with the
0337: following commands:
0338: 
0339: @table @kbd
0340: @item C-x <
0341: Scroll text in current window to the left (@code{scroll-left}).
0342: @item C-x >
0343: Scroll to the right (@code{scroll-right}).
0344: @end table
0345: 
0346: @kindex C-x <
0347: @kindex C-x >
0348: @findex scroll-left
0349: @findex scroll-right
0350:   @kbd{C-x <} (@code{scroll-left}) scrolls text in the selected window
0351: to the left by the full width of the window, less two columns.  (In
0352: other words, the text in the window moves left relative to the
0353: window.)  With a numeric argument @var{n}, it scrolls by @var{n}
0354: columns.
0355: 
0356:   If the text is scrolled to the left, and point moves off the left
0357: edge of the window, the cursor will freeze at the left edge of the
0358: window, until point moves back to the displayed portion of the text.
0359: This is independent of the current setting of
0360: @code{auto-hscroll-mode}, which, for text scrolled to the left, only
0361: affects the behavior at the right edge of the window.
0362: 
0363:   @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
0364: The window cannot be scrolled any farther to the right once it is
0365: displayed normally, with each line starting at the window's left
0366: margin; attempting to do so has no effect.  This means that you don't
0367: have to calculate the argument precisely for @w{@kbd{C-x >}}; any
0368: sufficiently large argument will restore the normal display.
0369: 
0370:   If you use those commands to scroll a window horizontally, that sets
0371: a lower bound for automatic horizontal scrolling.  Automatic scrolling
0372: will continue to scroll the window, but never farther to the right
0373: than the amount you previously set by @code{scroll-left}.  When
0374: @code{auto-hscroll-mode} is set to @code{current-line}, all the lines
0375: other than the one showing the cursor will be scrolled by that minimal
0376: amount.
0377: 
0378: @node Narrowing
0379: @section Narrowing
0380: @cindex widening
0381: @cindex restriction
0382: @cindex narrowing
0383: @cindex accessible portion
0384: 
0385:   @dfn{Narrowing} means focusing in on some portion of the buffer,
0386: making the rest temporarily inaccessible.  The portion which you can
0387: still get to is called the @dfn{accessible portion}.  Canceling the
0388: narrowing, which makes the entire buffer once again accessible, is
0389: called @dfn{widening}.  The bounds of narrowing in effect in a buffer
0390: are called the buffer's @dfn{restriction}.
0391: 
0392:   Narrowing can make it easier to concentrate on a single subroutine or
0393: paragraph by eliminating clutter.  It can also be used to limit the
0394: range of operation of a replace command or repeating keyboard macro.
0395: 
0396: @table @kbd
0397: @item C-x n n
0398: Narrow down to between point and mark (@code{narrow-to-region}).
0399: @item C-x n w
0400: Widen to make the entire buffer accessible again (@code{widen}).
0401: @item C-x n p
0402: Narrow down to the current page (@code{narrow-to-page}).
0403: @item C-x n d
0404: Narrow down to the current defun (@code{narrow-to-defun}).
0405: @end table
0406: 
0407:   When you have narrowed down to a part of the buffer, that part appears
0408: to be all there is.  You can't see the rest, you can't move into it
0409: (motion commands won't go outside the accessible part), you can't change
0410: it in any way.  However, it is not gone, and if you save the file all
0411: the inaccessible text will be saved.  The word @samp{Narrow} appears in
0412: the mode line whenever narrowing is in effect.
0413: 
0414: @kindex C-x n n
0415: @findex narrow-to-region
0416:   The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
0417: It sets the current buffer's restrictions so that the text in the current
0418: region remains accessible, but all text before the region or after the
0419: region is inaccessible.  Point and mark do not change.
0420: 
0421: @kindex C-x n p
0422: @findex narrow-to-page
0423: @kindex C-x n d
0424: @findex narrow-to-defun
0425:   Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
0426: down to the current page.  @xref{Pages}, for the definition of a page.
0427: @kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
0428: containing point (@pxref{Defuns}).
0429: 
0430: @kindex C-x n w
0431: @findex widen
0432:   The way to cancel narrowing is to widen with @kbd{C-x n w}
0433: (@code{widen}).  This makes all text in the buffer accessible again.
0434: 
0435:   You can get information on what part of the buffer you are narrowed down
0436: to using the @kbd{C-x =} command.  @xref{Position Info}.
0437: 
0438:   Because narrowing can easily confuse users who do not understand it,
0439: @code{narrow-to-region} is normally a disabled command.  Attempting to use
0440: this command asks for confirmation and gives you the option of enabling it;
0441: if you enable the command, confirmation will no longer be required for
0442: it.  @xref{Disabling}.
0443: 
0444: @node View Mode
0445: @section View Mode
0446: @cindex View mode
0447: @cindex mode, View
0448: 
0449: @kindex s @r{(View mode)}
0450: @kindex SPC @r{(View mode)}
0451: @kindex DEL @r{(View mode)}
0452:   View mode is a minor mode that lets you scan a buffer by sequential
0453: screenfuls.  It provides commands for scrolling through the buffer
0454: conveniently but not for changing it.  Apart from the usual Emacs
0455: cursor motion commands, you can type @key{SPC} to scroll forward one
0456: windowful, @kbd{S-@key{SPC}} or @key{DEL} to scroll backward, and @kbd{s} to
0457: start an incremental search.
0458: 
0459: @kindex q @r{(View mode)}
0460: @kindex e @r{(View mode)}
0461: @findex View-quit
0462: @findex View-exit
0463:   Typing @kbd{q} (@code{View-quit}) disables View mode, and switches
0464: back to the buffer and position before View mode was enabled.  Typing
0465: @kbd{e} (@code{View-exit}) disables View mode, keeping the current
0466: buffer and position.
0467: 
0468: @findex view-buffer
0469: @findex view-file
0470:   @kbd{M-x view-buffer} prompts for an existing Emacs buffer, switches
0471: to it, and enables View mode.  @kbd{M-x view-file} prompts for a file
0472: and visits it with View mode enabled.
0473: 
0474: @node Follow Mode
0475: @section Follow Mode
0476: @cindex Follow mode
0477: @cindex mode, Follow
0478: @findex follow-mode
0479: @cindex windows, synchronizing
0480: @cindex synchronizing windows
0481: 
0482:   @dfn{Follow mode} is a minor mode that makes two windows, both
0483: showing the same buffer, scroll as a single tall virtual window.
0484: To use Follow mode, go to a frame with just one window, split it into
0485: two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
0486: follow-mode}.  From then on, you can edit the buffer in either of the
0487: two windows, or scroll either one; the other window follows it.
0488: 
0489:   In Follow mode, if you move point outside the portion visible in one
0490: window and into the portion visible in the other window, that selects
0491: the other window---again, treating the two as if they were parts of
0492: one large window.
0493: 
0494:   To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
0495: 
0496: @node Faces
0497: @section Text Faces
0498: @cindex faces
0499: 
0500:   Emacs can display text in several different styles, called
0501: @dfn{faces}.  Each face can specify various @dfn{face attributes},
0502: such as the font, height, weight, slant, foreground and background
0503: color, and underlining or overlining.  Most major modes assign faces
0504: to the text automatically, via Font Lock mode.  @xref{Font Lock}, for
0505: more information about how these faces are assigned.
0506: 
0507: @findex list-faces-display
0508:   To see what faces are currently defined, and what they look like,
0509: type @kbd{M-x list-faces-display}.  With a prefix argument, this
0510: prompts for a regular expression, and displays only faces with names
0511: matching that regular expression (@pxref{Regexps}).
0512: 
0513: @vindex frame-background-mode
0514:   It's possible for a given face to look different in different
0515: frames.  For instance, some text terminals do not support all face
0516: attributes, particularly font, height, and width, and some support a
0517: limited range of colors.  In addition, most Emacs faces are defined so
0518: that their attributes are different on light and dark frame
0519: backgrounds, for reasons of legibility.  By default, Emacs
0520: automatically chooses which set of face attributes to display on each
0521: frame, based on the frame's current background color.  However, you
0522: can override this by giving the variable @code{frame-background-mode}
0523: a non-@code{nil} value.  A value of @code{dark} makes Emacs treat all
0524: frames as if they have a dark background, whereas a value of
0525: @code{light} makes it treat all frames as if they have a light
0526: background.
0527: 
0528: @cindex background color
0529: @cindex @code{default face}
0530:   You can customize a face to alter its attributes, and save those
0531: customizations for future Emacs sessions.  @xref{Face Customization},
0532: for details.
0533: 
0534:   The @code{default} face is the default for displaying text, and all
0535: of its attributes are specified.  Its background color is also used as
0536: the frame's background color.  @xref{Colors}.
0537: 
0538: @cindex @code{cursor} face
0539:   Another special face is the @code{cursor} face.  On graphical
0540: displays, the background color of this face is used to draw the text
0541: cursor.  None of the other attributes of this face have any effect;
0542: the foreground color for text under the cursor is taken from the
0543: background color of the underlying text.  On text terminals, the
0544: appearance of the text cursor is determined by the terminal, not by
0545: the @code{cursor} face.
0546: 
0547:   You can also use X resources to specify attributes of any particular
0548: face.  @xref{Resources}.
0549: 
0550:   Emacs can display variable-width fonts, but some Emacs commands,
0551: particularly indentation commands, do not account for variable
0552: character display widths.  Therefore, we recommend not using
0553: variable-width fonts for most faces, particularly those assigned by
0554: Font Lock mode.
0555: 
0556: @node Colors
0557: @section Colors for Faces
0558: @cindex color name
0559: @cindex RGB triplet
0560: 
0561:   Faces can have various foreground and background colors.  When you
0562: specify a color for a face---for instance, when customizing the face
0563: (@pxref{Face Customization})---you can use either a @dfn{color name}
0564: or an @dfn{RGB triplet}.
0565: 
0566: @findex list-colors-display
0567: @vindex list-colors-sort
0568:   A color name is a pre-defined name, such as @samp{dark orange} or
0569: @samp{medium sea green}.  To view a list of color names, type @kbd{M-x
0570: list-colors-display}.  To control the order in which colors are shown,
0571: customize @code{list-colors-sort}.  If you run this command on a
0572: graphical display, it shows the full range of color names known to
0573: Emacs (these are the standard X11 color names, defined in X's
0574: @file{rgb.txt} file).  If you run the command on a text terminal, it
0575: shows only a small subset of colors that can be safely displayed on
0576: such terminals.  However, Emacs understands X11 color names even on
0577: text terminals; if a face is given a color specified by an X11 color
0578: name, it is displayed using the closest-matching terminal color.
0579: 
0580:   An RGB triplet is a string of the form @samp{#RRGGBB}.  Each of the
0581: R, G, and B components is a hexadecimal number specifying the
0582: component's relative intensity, one to four digits long (usually two
0583: digits are used).  The components must have the same number of digits.
0584: For hexadecimal values A to F, either upper or lower case are
0585: acceptable.
0586: 
0587:   The @kbd{M-x list-colors-display} command also shows the equivalent
0588: RGB triplet for each named color.  For instance, @samp{medium sea
0589: green} is equivalent to @samp{#3CB371}.
0590: 
0591: @cindex face colors, setting
0592: @findex set-face-foreground
0593: @findex set-face-background
0594:   You can change the foreground and background colors of a face with
0595: @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
0596: These commands prompt in the minibuffer for a face name and a color,
0597: with completion, and then set that face to use the specified color.
0598: They affect the face colors on all frames, but their effects do not
0599: persist for future Emacs sessions, unlike using the customization
0600: buffer or X resources.  You can also use frame parameters to set
0601: foreground and background colors for a specific frame; @xref{Frame
0602: Parameters}.
0603: 
0604: @node Standard Faces
0605: @section Standard Faces
0606: @cindex standard faces
0607: 
0608:   Here are the standard faces for specifying text appearance.  You can
0609: apply them to specific text when you want the effects they produce.
0610: 
0611: @table @code
0612: @item default
0613: This face is used for ordinary text that doesn't specify any face.
0614: Its background color is used as the frame's background color.
0615: @item bold
0616: This face uses a bold variant of the default font.
0617: @item italic
0618: This face uses an italic variant of the default font.
0619: @item bold-italic
0620: This face uses a bold italic variant of the default font.
0621: @item underline
0622: This face underlines text.
0623: @item fixed-pitch
0624: This face forces use of a fixed-width font.  It's reasonable to
0625: customize this face to use a different fixed-width font, if you like,
0626: but you should not make it a variable-width font.
0627: @item fixed-pitch-serif
0628: This face is like @code{fixed-pitch}, except the font has serifs and
0629: looks more like traditional typewriting.
0630: @cindex @code{variable-pitch} face
0631: @item variable-pitch
0632: This face forces use of a variable-width font.
0633: @cindex @code{shadow} face
0634: @item shadow
0635: This face is used for making the text less noticeable than the surrounding
0636: ordinary text.  Usually this can be achieved by using shades of gray in
0637: contrast with either black or white default foreground color.
0638: @end table
0639: 
0640:   Here's an incomplete list of faces used to highlight parts of the
0641: text temporarily for specific purposes.  (Many other modes define
0642: their own faces for this purpose.)
0643: 
0644: @table @code
0645: @item highlight
0646: This face is used for text highlighting in various contexts, such as
0647: when the mouse cursor is moved over a hyperlink.
0648: @item isearch
0649: This face is used to highlight the current Isearch match
0650: (@pxref{Incremental Search}).
0651: @item query-replace
0652: This face is used to highlight the current Query Replace match
0653: (@pxref{Replace}).
0654: @item lazy-highlight
0655: This face is used to highlight lazy matches for Isearch and Query
0656: Replace (matches other than the current one).
0657: @item region
0658: This face is used for displaying an active region (@pxref{Mark}).
0659: When Emacs is built with GTK+ support, its colors are taken from the
0660: current GTK+ theme.
0661: @item secondary-selection
0662: This face is used for displaying a secondary X selection (@pxref{Secondary
0663: Selection}).
0664: @item trailing-whitespace
0665: The face for highlighting excess spaces and tabs at the end of a line
0666: when @code{show-trailing-whitespace} is non-@code{nil} (@pxref{Useless
0667: Whitespace}).
0668: @item escape-glyph
0669: The face for displaying control characters and escape sequences
0670: (@pxref{Text Display}).
0671: @item homoglyph
0672: The face for displaying lookalike characters, i.e., characters that
0673: look like but are not the characters being represented
0674: (@pxref{Text Display}).
0675: @item nobreak-space
0676: The face for displaying no-break space characters (@pxref{Text
0677: Display}).
0678: @item nobreak-hyphen
0679: The face for displaying no-break hyphen characters (@pxref{Text
0680: Display}).
0681: @end table
0682: 
0683:   The following faces control the appearance of parts of the Emacs
0684: frame:
0685: 
0686: @table @code
0687: @item mode-line
0688: @cindex @code{mode-line} face
0689: @cindex faces for mode lines
0690: This face is used for the mode line of the currently selected window,
0691: and for menu bars when toolkit menus are not used.  By default, it's
0692: drawn with shadows for a raised effect on graphical displays, and
0693: drawn as the inverse of the default face on non-windowed terminals.
0694: @item mode-line-inactive
0695: @cindex @code{mode-line-inactive} face
0696: Like @code{mode-line}, but used for mode lines of the windows other
0697: than the selected one (if @code{mode-line-in-non-selected-windows} is
0698: non-@code{nil}).  This face inherits from @code{mode-line}, so changes
0699: in that face affect mode lines in all windows.
0700: @item mode-line-highlight
0701: @cindex @code{mode-line-highlight} face
0702: Like @code{highlight}, but used for mouse-sensitive portions of text
0703: on mode lines.  Such portions of text typically pop up tooltips
0704: (@pxref{Tooltips}) when the mouse pointer hovers above them.
0705: @item mode-line-buffer-id
0706: @cindex @code{mode-line-buffer-id} face
0707: This face is used for buffer identification parts in the mode line.
0708: @item header-line
0709: @cindex @code{header-line} face
0710: Similar to @code{mode-line} for a window's header line, which appears
0711: at the top of a window just as the mode line appears at the bottom.
0712: Most windows do not have a header line---only some special modes, such
0713: Info mode, create one.
0714: @item header-line-highlight
0715: @cindex @code{header-line-highlight} face
0716: Similar to @code{highlight} and @code{mode-line-highlight}, but used
0717: for mouse-sensitive portions of text on header lines.  This is a
0718: separate face because the @code{header-line} face might be customized
0719: in a way that does not interact well with @code{highlight}.
0720: @item vertical-border
0721: @cindex @code{vertical-border} face
0722: This face is used for the vertical divider between windows on text
0723: terminals.
0724: @item minibuffer-prompt
0725: @cindex @code{minibuffer-prompt} face
0726: @vindex minibuffer-prompt-properties
0727: This face is used for the prompt strings displayed in the minibuffer.
0728: By default, Emacs automatically adds this face to the value of
0729: @code{minibuffer-prompt-properties}, which is a list of text
0730: properties (@pxref{Text Properties,,, elisp, the Emacs Lisp Reference
0731: Manual}) used to display the prompt text.  (This variable takes effect
0732: when you enter the minibuffer.)
0733: @item fringe
0734: @cindex @code{fringe} face
0735: The face for the fringes to the left and right of windows on graphic
0736: displays.  (The fringes are the narrow portions of the Emacs frame
0737: between the text area and the window's right and left borders.)
0738: @xref{Fringes}.
0739: @item cursor
0740: The @code{:background} attribute of this face specifies the color of
0741: the text cursor.  @xref{Cursor Display}.
0742: @item tooltip
0743: This face is used for tooltip text.  By default, if Emacs is built
0744: with GTK+ support, tooltips are drawn via GTK+ and this face has no
0745: effect.  @xref{Tooltips}.
0746: @item mouse
0747: This face determines the color of the mouse pointer.
0748: @end table
0749: 
0750:   The following faces likewise control the appearance of parts of the
0751: Emacs frame, but only on text terminals, or when Emacs is built on X
0752: with no toolkit support.  (For all other cases, the appearance of the
0753: respective frame elements is determined by system-wide settings.)
0754: 
0755: @table @code
0756: @item scroll-bar
0757: This face determines the visual appearance of the scroll bar.
0758: @xref{Scroll Bars}.
0759: @item tool-bar
0760: This face determines the color of tool bar icons.  @xref{Tool Bars}.
0761: @item menu
0762: @cindex menu bar appearance
0763: @cindex @code{menu} face, no effect if customized
0764: @cindex customization of @code{menu} face
0765: This face determines the colors and font of Emacs's menus.  @xref{Menu
0766: Bars}.
0767: @item tty-menu-enabled-face
0768: @cindex faces for text-mode menus
0769: @cindex TTY menu faces
0770: This face is used to display enabled menu items on text-mode
0771: terminals.
0772: @item tty-menu-disabled-face
0773: This face is used to display disabled menu items on text-mode
0774: terminals.
0775: @item tty-menu-selected-face
0776: This face is used to display on text-mode terminals the menu item that
0777: would be selected if you click a mouse or press @key{RET}.
0778: @end table
0779: 
0780: @node Text Scale
0781: @section Text Scale
0782: 
0783: @cindex adjust buffer face height
0784: @findex text-scale-adjust
0785: @kindex C-x C-+
0786: @kindex C-x C--
0787: @kindex C-x C-=
0788: @kindex C-x C-0
0789:   To increase the height of the default face in the current buffer,
0790: type @kbd{C-x C-+} or @kbd{C-x C-=}.  To decrease it, type @kbd{C-x
0791: C--}.  To restore the default (global) face height, type @kbd{C-x
0792: C-0}.  These keys are all bound to the same command,
0793: @code{text-scale-adjust}, which looks at the last key typed to
0794: determine which action to take.
0795: 
0796:   The final key of these commands may be repeated without the leading
0797: @kbd{C-x}.  For instance, @kbd{C-x C-= C-= C-=} increases the face
0798: height by three steps.  Each step scales the text height by a factor
0799: of 1.2; to change this factor, customize the variable
0800: @code{text-scale-mode-step}.  A numeric argument of 0
0801: to the @code{text-scale-adjust} command restores the default height,
0802: the same as typing @kbd{C-x C-0}.
0803: 
0804: @cindex increase buffer face height
0805: @findex text-scale-increase
0806: @cindex decrease buffer face height
0807: @findex text-scale-decrease
0808:   The commands @code{text-scale-increase} and
0809: @code{text-scale-decrease} increase or decrease the height of the
0810: default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively.
0811: You may find it convenient to bind to these commands, rather than
0812: @code{text-scale-adjust}.
0813: 
0814: @cindex set buffer face height
0815: @findex text-scale-set
0816:   The command @code{text-scale-set} scales the height of the default
0817: face in the current buffer to an absolute level specified by its
0818: prefix argument.
0819: 
0820: @findex text-scale-mode
0821:   The above commands automatically enable the minor mode
0822: @code{text-scale-mode} if the current font scaling is other than 1,
0823: and disable it otherwise.
0824: 
0825: @node Font Lock
0826: @section Font Lock mode
0827: @cindex Font Lock mode
0828: @cindex mode, Font Lock
0829: @cindex syntax highlighting and coloring
0830: 
0831:   Font Lock mode is a minor mode, always local to a particular buffer,
0832: which assigns faces to (or @dfn{fontifies}) the text in the buffer.
0833: Each buffer's major mode tells Font Lock mode which text to fontify;
0834: for instance, programming language modes fontify syntactically
0835: relevant constructs like comments, strings, and function names.
0836: 
0837: @findex font-lock-mode
0838:   Font Lock mode is enabled by default.  To toggle it in the current
0839: buffer, type @kbd{M-x font-lock-mode}.  A positive numeric argument
0840: unconditionally enables Font Lock mode, and a negative or zero
0841: argument disables it.
0842: 
0843: @findex global-font-lock-mode
0844: @vindex global-font-lock-mode
0845:   Type @kbd{M-x global-font-lock-mode} to toggle Font Lock mode in all
0846: buffers.  To impose this setting for future Emacs sessions, customize
0847: the variable @code{global-font-lock-mode} (@pxref{Easy
0848: Customization}), or add the following line to your init file:
0849: 
0850: @example
0851: (global-font-lock-mode 0)
0852: @end example
0853: 
0854: @noindent
0855: If you have disabled Global Font Lock mode, you can still enable Font
0856: Lock for specific major modes by adding the function
0857: @code{font-lock-mode} to the mode hooks (@pxref{Hooks}).  For example,
0858: to enable Font Lock mode for editing C files, you can do this:
0859: 
0860: @example
0861: (add-hook 'c-mode-hook 'font-lock-mode)
0862: @end example
0863: 
0864:   Font Lock mode uses several specifically named faces to do its job,
0865: including @code{font-lock-string-face}, @code{font-lock-comment-face},
0866: and others.  The easiest way to find them all is to use @kbd{M-x
0867: customize-group @key{RET} font-lock-faces @key{RET}}.  You can then
0868: use that customization buffer to customize the appearance of these
0869: faces.  @xref{Face Customization}.
0870: 
0871: @vindex font-lock-maximum-decoration
0872:   You can customize the variable @code{font-lock-maximum-decoration}
0873: to alter the amount of fontification applied by Font Lock mode, for
0874: major modes that support this feature.  The value should be a number
0875: (with 1 representing a minimal amount of fontification; some modes
0876: support levels as high as 3); or @code{t}, meaning ``as high as
0877: possible'' (the default).  To be effective for a given file buffer,
0878: the customization of @code{font-lock-maximum-decoration} should be
0879: done @emph{before} the file is visited; if you already have the file
0880: visited in a buffer when you customize this variable, kill the buffer
0881: and visit the file again after the customization.
0882: 
0883: You can also specify different numbers for particular major modes; for
0884: example, to use level 1 for C/C++ modes, and the default level
0885: otherwise, use the value
0886: 
0887: @example
0888: '((c-mode . 1) (c++-mode . 1)))
0889: @end example
0890: 
0891: @cindex incorrect fontification
0892: @cindex parenthesis in column zero and fontification
0893: @cindex brace in column zero and fontification
0894:   Comment and string fontification (or ``syntactic'' fontification)
0895: relies on analysis of the syntactic structure of the buffer text.  For
0896: the sake of speed, some modes, including Lisp mode, rely on a special
0897: convention: an open-parenthesis or open-brace in the leftmost column
0898: always defines the beginning of a defun, and is thus always outside
0899: any string or comment.  Therefore, you should avoid placing an
0900: open-parenthesis or open-brace in the leftmost column, if it is inside
0901: a string or comment.  @xref{Left Margin Paren}, for details.
0902: 
0903: @findex font-lock-add-keywords
0904:   Font Lock highlighting patterns already exist for most modes, but
0905: you may want to fontify additional patterns.  You can use the function
0906: @code{font-lock-add-keywords}, to add your own highlighting patterns
0907: for a particular mode.  For example, to highlight @samp{FIXME:} words
0908: in C comments, use this:
0909: 
0910: @example
0911: (add-hook 'c-mode-hook
0912:           (lambda ()
0913:            (font-lock-add-keywords nil
0914:             '(("\\<\\(FIXME\\):" 1
0915:                font-lock-warning-face t)))))
0916: @end example
0917: 
0918: @findex font-lock-remove-keywords
0919: @noindent
0920: To remove keywords from the font-lock highlighting patterns, use the
0921: function @code{font-lock-remove-keywords}.  @xref{Search-based
0922: Fontification,,, elisp, The Emacs Lisp Reference Manual}.
0923: 
0924: @cindex just-in-time (JIT) font-lock
0925: @cindex background syntax highlighting
0926:   Fontifying large buffers can take a long time.  To avoid large
0927: delays when a file is visited, Emacs initially fontifies only the
0928: visible portion of a buffer.  As you scroll through the buffer, each
0929: portion that becomes visible is fontified as soon as it is displayed;
0930: this type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT})
0931: Lock.  You can control how JIT Lock behaves, including telling it to
0932: perform fontification while idle, by customizing variables in the
0933: customization group @samp{jit-lock}.  @xref{Specific Customization}.
0934: 
0935: @node Highlight Interactively
0936: @section Interactive Highlighting
0937: @cindex highlighting by matching
0938: @cindex interactive highlighting
0939: @cindex Highlight Changes mode
0940: 
0941: @findex highlight-changes-mode
0942: Highlight Changes mode is a minor mode that @dfn{highlights} the parts
0943: of the buffer that were changed most recently, by giving that text a
0944: different face.  To enable or disable Highlight Changes mode, use
0945: @kbd{M-x highlight-changes-mode}.
0946: 
0947: @cindex Hi Lock mode
0948: @findex hi-lock-mode
0949:   Hi Lock mode is a minor mode that highlights text that matches
0950: regular expressions you specify.  For example, you can use it to
0951: highlight all the references to a certain variable in a program source
0952: file, highlight certain parts in a voluminous output of some program,
0953: or highlight certain names in an article.  To enable or disable Hi
0954: Lock mode, use the command @kbd{M-x hi-lock-mode}.  To enable Hi Lock
0955: mode for all buffers, use @kbd{M-x global-hi-lock-mode} or place
0956: @code{(global-hi-lock-mode 1)} in your @file{.emacs} file.
0957: 
0958:   Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except
0959: that you specify explicitly the regular expressions to highlight.  You
0960: can control them with the following commands.  (The key bindings
0961: below that begin with @kbd{C-x w} are deprecated in favor of the
0962: global @kbd{M-s h} bindings, and will be removed in some future Emacs
0963: version.)
0964: 
0965: @table @kbd
0966: @item M-s h r @var{regexp} @key{RET} @var{face} @key{RET}
0967: @itemx C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
0968: @kindex M-s h r
0969: @kindex C-x w h
0970: @findex highlight-regexp
0971: Highlight text that matches @var{regexp} using face @var{face}
0972: (@code{highlight-regexp}).  The highlighting will remain as long as
0973: the buffer is loaded.  For example, to highlight all occurrences of
0974: the word ``whim'' using the default face (a yellow background), type
0975: @kbd{M-s h r whim @key{RET} @key{RET}}.  Any face can be used for
0976: highlighting, Hi Lock provides several of its own and these are
0977: pre-loaded into a list of default values.  While being prompted for a
0978: face use @kbd{M-n} and @kbd{M-p} to cycle through them.  A prefix
0979: numeric argument limits the highlighting to the corresponding
0980: subexpression.
0981: 
0982: @vindex hi-lock-auto-select-face
0983: Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil}
0984: value causes this command (and other Hi Lock commands that read faces)
0985: to automatically choose the next face from the default list without
0986: prompting.
0987: 
0988: You can use this command multiple times, specifying various regular
0989: expressions to highlight in different ways.
0990: 
0991: @item M-s h u @var{regexp} @key{RET}
0992: @itemx C-x w r @var{regexp} @key{RET}
0993: @kindex M-s h u
0994: @kindex C-x w r
0995: @findex unhighlight-regexp
0996: Unhighlight @var{regexp} (@code{unhighlight-regexp}).  If you invoke
0997: this from the menu, you select the expression to unhighlight from a
0998: list.  If you invoke this from the keyboard, you use the minibuffer.
0999: It will show the most recently added regular expression; use @kbd{M-n}
1000: to show the next older expression and @kbd{M-p} to select the next
1001: newer expression.  (You can also type the expression by hand, with
1002: completion.)  When the expression you want to unhighlight appears in
1003: the minibuffer, press @kbd{@key{RET}} to exit the minibuffer and
1004: unhighlight it.
1005: 
1006: @item M-s h l @var{regexp} @key{RET} @var{face} @key{RET}
1007: @itemx C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
1008: @kindex M-s h l
1009: @kindex C-x w l
1010: @findex highlight-lines-matching-regexp
1011: @cindex lines, highlighting
1012: @cindex highlighting lines of text
1013: Highlight entire lines containing a match for @var{regexp}, using face
1014: @var{face} (@code{highlight-lines-matching-regexp}).
1015: 
1016: @item M-s h p @var{phrase} @key{RET} @var{face} @key{RET}
1017: @itemx C-x w p @var{phrase} @key{RET} @var{face} @key{RET}
1018: @kindex M-s h p
1019: @kindex C-x w p
1020: @findex highlight-phrase
1021: @cindex phrase, highlighting
1022: @cindex highlighting phrase
1023: Highlight matches of @var{phrase}, using face @var{face}
1024: (@code{highlight-phrase}).  @var{phrase} can be any regexp,
1025: but spaces will be replaced by matches to whitespace and
1026: initial lower-case letters will become case insensitive.
1027: 
1028: @item M-s h .
1029: @itemx C-x w .
1030: @kindex M-s h .
1031: @kindex C-x w .
1032: @findex highlight-symbol-at-point
1033: @cindex symbol, highlighting
1034: @cindex highlighting symbol at point
1035: Highlight the symbol found near point, using the next available face
1036: (@code{highlight-symbol-at-point}).
1037: 
1038: @item M-s h w
1039: @itemx C-x w b
1040: @kindex M-s h w
1041: @kindex C-x w b
1042: @findex hi-lock-write-interactive-patterns
1043: Insert all the current highlighting regexp/face pairs into the buffer
1044: at point, with comment delimiters to prevent them from changing your
1045: program.  (This key binding runs the
1046: @code{hi-lock-write-interactive-patterns} command.)
1047: 
1048: These patterns are extracted from the comments, if appropriate, if you
1049: invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while
1050: Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}).
1051: 
1052: @item M-s h f
1053: @itemx C-x w i
1054: @kindex M-s h f
1055: @kindex C-x w i
1056: @findex hi-lock-find-patterns
1057: Extract regexp/face pairs from comments in the current buffer
1058: (@code{hi-lock-find-patterns}).  Thus, you can enter patterns
1059: interactively with @code{highlight-regexp}, store them into the file
1060: with @code{hi-lock-write-interactive-patterns}, edit them (perhaps
1061: including different faces for different parenthesized parts of the
1062: match), and finally use this command (@code{hi-lock-find-patterns}) to
1063: have Hi Lock highlight the edited patterns.
1064: 
1065: @vindex hi-lock-file-patterns-policy
1066: The variable @code{hi-lock-file-patterns-policy} controls whether Hi
1067: Lock mode should automatically extract and highlight patterns found in a
1068: file when it is visited.  Its value can be @code{nil} (never highlight),
1069: @code{ask} (query the user), or a function.  If it is a function,
1070: @code{hi-lock-find-patterns} calls it with the patterns as argument; if
1071: the function returns non-@code{nil}, the patterns are used.  The default
1072: is @code{ask}.  Note that patterns are always highlighted if you call
1073: @code{hi-lock-find-patterns} directly, regardless of the value of this
1074: variable.
1075: 
1076: @vindex hi-lock-exclude-modes
1077: Also, @code{hi-lock-find-patterns} does nothing if the current major
1078: mode's symbol is a member of the list @code{hi-lock-exclude-modes}.
1079: @end table
1080: 
1081: @node Fringes
1082: @section Window Fringes
1083: @cindex fringes
1084: 
1085: @findex set-fringe-style
1086: @findex fringe-mode
1087: @vindex fringe-mode @r{(variable)}
1088:   On graphical displays, each Emacs window normally has narrow
1089: @dfn{fringes} on the left and right edges.  The fringes are used to
1090: display symbols that provide information about the text in the window.
1091: You can type @kbd{M-x fringe-mode} to toggle display of the fringes or
1092: to modify their width.  This command affects fringes in all frames; to
1093: modify fringes on the selected frame only, use @kbd{M-x
1094: set-fringe-style}.  You can make your changes to the fringes permanent
1095: by customizing the variable @code{fringe-mode}.
1096: 
1097:   The most common use of the fringes is to indicate a continuation
1098: line (@pxref{Continuation Lines}).  When one line of text is split
1099: into multiple screen lines, the left fringe shows a curving arrow for
1100: each screen line except the first, indicating that this is not the
1101: real beginning.  The right fringe shows a curving arrow for each
1102: screen line except the last, indicating that this is not the real
1103: end.  If the line's direction is right-to-left (@pxref{Bidirectional
1104: Editing}), the meanings of the curving arrows in the fringes are
1105: swapped.
1106: 
1107:   The fringes indicate line truncation (@pxref{Line Truncation}) with
1108: short horizontal arrows meaning there's more text on this line which
1109: is scrolled horizontally out of view.  Clicking the mouse on one of
1110: the arrows scrolls the display horizontally in the direction of the
1111: arrow.
1112: 
1113:   The fringes can also indicate other things, such as buffer
1114: boundaries (@pxref{Displaying Boundaries}), and where a program you
1115: are debugging is executing (@pxref{Debuggers}).
1116: 
1117: @vindex overflow-newline-into-fringe
1118:   The fringe is also used for drawing the cursor, if the current line
1119: is exactly as wide as the window and point is at the end of the line.
1120: To disable this, change the variable
1121: @code{overflow-newline-into-fringe} to @code{nil}; this causes Emacs
1122: to continue or truncate lines that are exactly as wide as the window.
1123: 
1124:   If you customize @code{fringe-mode} to remove the fringes on one or
1125: both sides of the window display, the features that display on the
1126: fringe are not available.  Indicators of line continuation and
1127: truncation are an exception: when fringes are not available, Emacs
1128: uses the leftmost and rightmost character cells to indicate
1129: continuation and truncation with special ASCII characters, see
1130: @ref{Continuation Lines}, and @ref{Line Truncation}.  This reduces the
1131: width available for displaying text on each line, because the
1132: character cells used for truncation and continuation indicators are
1133: reserved for that purpose.  Since buffer text can include
1134: bidirectional text, and thus both left-to-right and right-to-left
1135: paragraphs (@pxref{Bidirectional Editing}), removing only one of the
1136: fringes still reserves two character cells, one on each side of the
1137: window, for truncation and continuation indicators, because these
1138: indicators are displayed on opposite sides of the window in
1139: right-to-left paragraphs.
1140: 
1141: @node Displaying Boundaries
1142: @section Displaying Boundaries
1143: 
1144: @vindex indicate-buffer-boundaries
1145:   On graphical displays, Emacs can indicate the buffer boundaries in
1146: the fringes.  If you enable this feature, the first line and the last
1147: line are marked with angle images in the fringes.  This can be
1148: combined with up and down arrow images which say whether it is
1149: possible to scroll the window.
1150: 
1151:   The buffer-local variable @code{indicate-buffer-boundaries} controls
1152: how the buffer boundaries and window scrolling is indicated in the
1153: fringes.  If the value is @code{left} or @code{right}, both angle and
1154: arrow bitmaps are displayed in the left or right fringe, respectively.
1155: 
1156:   If value is an alist (@pxref{Association Lists,,, elisp, the Emacs
1157: Lisp Reference Manual}), each element @code{(@var{indicator} .
1158: @var{position})} specifies the position of one of the indicators.  The
1159: @var{indicator} must be one of @code{top}, @code{bottom}, @code{up},
1160: @code{down}, or @code{t} which specifies the default position for the
1161: indicators not present in the alist.  The @var{position} is one of
1162: @code{left}, @code{right}, or @code{nil} which specifies not to show
1163: this indicator.
1164: 
1165:   For example, @code{((top . left) (t . right))} places the top angle
1166: bitmap in left fringe, the bottom angle bitmap in right fringe, and
1167: both arrow bitmaps in right fringe.  To show just the angle bitmaps in
1168: the left fringe, but no arrow bitmaps, use @code{((top .  left)
1169: (bottom . left))}.
1170: 
1171: @node Useless Whitespace
1172: @section Useless Whitespace
1173: 
1174: @cindex trailing whitespace
1175: @cindex whitespace, trailing
1176: @vindex show-trailing-whitespace
1177:   It is easy to leave unnecessary spaces at the end of a line, or
1178: empty lines at the end of a buffer, without realizing it.  In most
1179: cases, this @dfn{trailing whitespace} has no effect, but sometimes it
1180: can be a nuisance.
1181: 
1182: @cindex @code{trailing-whitespace} face
1183:   You can make trailing whitespace at the end of a line visible by
1184: setting the buffer-local variable @code{show-trailing-whitespace} to
1185: @code{t}.  Then Emacs displays trailing whitespace, using the face
1186: @code{trailing-whitespace}.
1187: 
1188:   This feature does not apply when point is at the end of the line
1189: containing the whitespace.  Strictly speaking, that is trailing
1190: whitespace nonetheless, but displaying it specially in that case
1191: looks ugly while you are typing in new text.  In this special case,
1192: the location of point is enough to show you that the spaces are
1193: present.
1194: 
1195: @findex delete-trailing-whitespace
1196: @vindex delete-trailing-lines
1197:   Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
1198: whitespace.  This command deletes all extra spaces at the end of each
1199: line in the buffer, and all empty lines at the end of the buffer; to
1200: ignore the latter, change the variable @code{delete-trailing-lines} to
1201: @code{nil}.  If the region is active, the command instead deletes
1202: extra spaces at the end of each line in the region.
1203: 
1204: @vindex indicate-empty-lines
1205: @cindex unused lines
1206: @cindex fringes, and unused line indication
1207:   On graphical displays, Emacs can indicate unused lines at the end of
1208: the window with a small image in the left fringe (@pxref{Fringes}).
1209: The image appears for screen lines that do not correspond to any
1210: buffer text, so blank lines at the end of the buffer stand out because
1211: they lack this image.  To enable this feature, set the buffer-local
1212: variable @code{indicate-empty-lines} to a non-@code{nil} value.  You
1213: can enable or disable this feature for all new buffers by setting the
1214: default value of this variable, e.g., @code{(setq-default
1215: indicate-empty-lines t)}.
1216: 
1217: @cindex Whitespace mode
1218: @cindex mode, Whitespace
1219: @findex whitespace-mode
1220: @vindex whitespace-style
1221: @findex whitespace-toggle-options
1222:   Whitespace mode is a buffer-local minor mode that lets you
1223: visualize many kinds of whitespace in the buffer, by either
1224: drawing the whitespace characters with a special face or displaying
1225: them as special glyphs.  To toggle this mode, type @kbd{M-x
1226: whitespace-mode}.  The kinds of whitespace visualized are determined
1227: by the list variable @code{whitespace-style}.  Individual elements in
1228: that list can be toggled on or off in the current buffer by typing
1229: @w{@kbd{M-x whitespace-toggle-options}}.  Here is a partial list
1230: of possible elements (see the variable's documentation for the full
1231: list):
1232: 
1233: @table @code
1234: @item face
1235: Enable all visualizations which use special faces.  This element has a
1236: special meaning: if it is absent from the list, none of the other
1237: visualizations take effect except @code{space-mark}, @code{tab-mark},
1238: and @code{newline-mark}.
1239: 
1240: @item trailing
1241: Highlight trailing whitespace.
1242: 
1243: @item tabs
1244: Highlight tab characters.
1245: 
1246: @item spaces
1247: Highlight space and non-breaking space characters.
1248: 
1249: @item lines
1250: @vindex whitespace-line-column
1251: Highlight lines longer than 80 columns.  To change the column limit,
1252: customize the variable @code{whitespace-line-column}.
1253: 
1254: @item newline
1255: Highlight newlines.
1256: 
1257: @item empty
1258: Highlight empty lines at the beginning and/or end of the buffer.
1259: 
1260: @item big-indent
1261: @vindex whitespace-big-indent-regexp
1262: Highlight too-deep indentation.  By default any sequence of at least 4
1263: consecutive tab characters or 32 consecutive space characters is
1264: highlighted.  To change that, customize the regular expression
1265: @code{whitespace-big-indent-regexp}.
1266: 
1267: @item space-mark
1268: Draw space and non-breaking characters with a special glyph.
1269: 
1270: @item tab-mark
1271: Draw tab characters with a special glyph.
1272: 
1273: @item newline-mark
1274: Draw newline characters with a special glyph.
1275: @end table
1276: 
1277: @findex global-whitespace-toggle-options
1278: @findex global-whitespace-mode
1279: Global Whitespace mode is a global minor mode that lets you visualize
1280: whitespace in all buffers.  To toggle individual features, use
1281: @kbd{M-x global-whitespace-toggle-options}.
1282: 
1283: @node Selective Display
1284: @section Selective Display
1285: @cindex selective display
1286: @findex set-selective-display
1287: @kindex C-x $
1288: 
1289:   Emacs has the ability to hide lines indented more than a given
1290: number of columns.  You can use this to get an overview of a part of a
1291: program.
1292: 
1293:   To hide lines in the current buffer, type @kbd{C-x $}
1294: (@code{set-selective-display}) with a numeric argument @var{n}.  Then
1295: lines with at least @var{n} columns of indentation disappear from the
1296: screen.  The only indication of their presence is that three dots
1297: (@samp{@dots{}}) appear at the end of each visible line that is
1298: followed by one or more hidden ones.
1299: 
1300:   The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
1301: if they were not there.
1302: 
1303:   The hidden lines are still present in the buffer, and most editing
1304: commands see them as usual, so you may find point in the middle of the
1305: hidden text.  When this happens, the cursor appears at the end of the
1306: previous line, after the three dots.  If point is at the end of the
1307: visible line, before the newline that ends it, the cursor appears before
1308: the three dots.
1309: 
1310:   To make all lines visible again, type @kbd{C-x $} with no argument.
1311: 
1312: @vindex selective-display-ellipses
1313:   If you set the variable @code{selective-display-ellipses} to
1314: @code{nil}, the three dots do not appear at the end of a line that
1315: precedes hidden lines.  Then there is no visible indication of the
1316: hidden lines.  This variable becomes local automatically when set.
1317: 
1318:   See also @ref{Outline Mode} for another way to hide part of
1319: the text in a buffer.
1320: 
1321: @node Optional Mode Line
1322: @section Optional Mode Line Features
1323: 
1324: @cindex buffer size display
1325: @cindex display of buffer size
1326: @findex size-indication-mode
1327:   The buffer percentage @var{pos} indicates the percentage of the
1328: buffer above the top of the window.  You can additionally display the
1329: size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
1330: Size Indication mode.  The size will be displayed immediately
1331: following the buffer percentage like this:
1332: 
1333: @example
1334: @var{pos} of @var{size}
1335: @end example
1336: 
1337: @noindent
1338: Here @var{size} is the human readable representation of the number of
1339: characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
1340: for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
1341: 
1342: @cindex line number display
1343: @cindex display of current line number
1344: @findex line-number-mode
1345:   The current line number of point appears in the mode line when Line
1346: Number mode is enabled.  Use the command @kbd{M-x line-number-mode} to
1347: turn this mode on and off; normally it is on.  The line number appears
1348: after the buffer percentage @var{pos}, with the letter @samp{L} to
1349: indicate what it is.
1350: 
1351: @cindex Column Number mode
1352: @cindex mode, Column Number
1353: @findex column-number-mode
1354:   Similarly, you can display the current column number by turning on
1355: Column Number mode with @kbd{M-x column-number-mode}.  The column
1356: number is indicated by the letter @samp{C}.  However, when both of
1357: these modes are enabled, the line and column numbers are displayed in
1358: parentheses, the line number first, rather than with @samp{L} and
1359: @samp{C}.  For example: @samp{(561,2)}.  @xref{Minor Modes}, for more
1360: information about minor modes and about how to use these commands.
1361: 
1362: @vindex column-number-indicator-zero-based
1363:   In Column Number mode, the displayed column number counts from zero
1364: starting at the left margin of the window.  If you would prefer for
1365: the displayed column number to count from one, you may set
1366: @code{column-number-indicator-zero-based} to @code{nil}.
1367: 
1368: @cindex narrowing, and line number display
1369:   If you have narrowed the buffer (@pxref{Narrowing}), the displayed
1370: line number is relative to the accessible portion of the buffer.
1371: Thus, it isn't suitable as an argument to @code{goto-line}.  (Use
1372: @code{what-line} command to see the line number relative to the whole
1373: file.)
1374: 
1375: @vindex line-number-display-limit
1376:   If the buffer is very large (larger than the value of
1377: @code{line-number-display-limit}), Emacs won't compute the line
1378: number, because that would be too slow; therefore, the line number
1379: won't appear on the mode-line.  To remove this limit, set
1380: @code{line-number-display-limit} to @code{nil}.
1381: 
1382: @vindex line-number-display-limit-width
1383:   Line-number computation can also be slow if the lines in the buffer
1384: are too long.  For this reason, Emacs doesn't display line numbers if
1385: the average width, in characters, of lines near point is larger than
1386: the value of @code{line-number-display-limit-width}.  The default
1387: value is 200 characters.
1388: 
1389: @findex display-time
1390: @cindex time (on mode line)
1391:   Emacs can optionally display the time and system load in all mode
1392: lines.  To enable this feature, type @kbd{M-x display-time} or customize
1393: the option @code{display-time-mode}.  The information added to the mode
1394: line looks like this:
1395: 
1396: @example
1397: @var{hh}:@var{mm}PM @var{l.ll}
1398: @end example
1399: 
1400: @noindent
1401: @vindex display-time-24hr-format
1402: Here @var{hh} and @var{mm} are the hour and minute, followed always by
1403: @samp{AM} or @samp{PM}.  @var{l.ll} is the average number, collected
1404: for the last few minutes, of processes in the whole system that were
1405: either running or ready to run (i.e., were waiting for an available
1406: processor).  (Some fields may be missing if your operating system
1407: cannot support them.)  If you prefer time display in 24-hour format,
1408: set the variable @code{display-time-24hr-format} to @code{t}.
1409: 
1410: @cindex mail (on mode line)
1411: @vindex display-time-use-mail-icon
1412: @vindex display-time-mail-face
1413: @vindex display-time-mail-file
1414: @vindex display-time-mail-directory
1415:   The word @samp{Mail} appears after the load level if there is mail
1416: for you that you have not read yet.  On graphical displays, you can
1417: use an icon instead of @samp{Mail} by customizing
1418: @code{display-time-use-mail-icon}; this may save some space on the
1419: mode line.  You can customize @code{display-time-mail-face} to make
1420: the mail indicator prominent.  Use @code{display-time-mail-file} to
1421: specify the mail file to check, or set
1422: @code{display-time-mail-directory} to specify the directory to check
1423: for incoming mail (any nonempty regular file in the directory is
1424: considered to be newly arrived mail).
1425: 
1426: @cindex battery status (on mode line)
1427: @findex display-battery-mode
1428: @vindex display-battery-mode
1429: @vindex battery-mode-line-format
1430:   When running Emacs on a laptop computer, you can display the battery
1431: charge on the mode-line, by using the command
1432: @code{display-battery-mode} or customizing the variable
1433: @code{display-battery-mode}.  The variable
1434: @code{battery-mode-line-format} determines the way the battery charge
1435: is displayed; the exact mode-line message depends on the operating
1436: system, and it usually shows the current battery charge as a
1437: percentage of the total charge.
1438: 
1439: @cindex mode line, 3D appearance
1440: @cindex attributes of mode line, changing
1441: @cindex non-integral number of lines in a window
1442:   On graphical displays, the mode line is drawn as a 3D box.  If you
1443: don't like this effect, you can disable it by customizing the
1444: @code{mode-line} face and setting its @code{box} attribute to
1445: @code{nil}.  @xref{Face Customization}.
1446: 
1447: @cindex non-selected windows, mode line appearance
1448:   By default, the mode line of nonselected windows is displayed in a
1449: different face, called @code{mode-line-inactive}.  Only the selected
1450: window is displayed in the @code{mode-line} face.  This helps show
1451: which window is selected.  When the minibuffer is selected, since
1452: it has no mode line, the window from which you activated the minibuffer
1453: has its mode line displayed using @code{mode-line}; as a result,
1454: ordinary entry to the minibuffer does not change any mode lines.
1455: 
1456: @vindex mode-line-in-non-selected-windows
1457:   You can disable use of @code{mode-line-inactive} by setting variable
1458: @code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
1459: lines are displayed in the @code{mode-line} face.
1460: 
1461: @vindex eol-mnemonic-unix
1462: @vindex eol-mnemonic-dos
1463: @vindex eol-mnemonic-mac
1464: @vindex eol-mnemonic-undecided
1465:   You can customize the mode line display for each of the end-of-line
1466: formats by setting each of the variables @code{eol-mnemonic-unix},
1467: @code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and
1468: @code{eol-mnemonic-undecided} to the strings you prefer.
1469: 
1470: @node Text Display
1471: @section How Text Is Displayed
1472: @cindex characters (in text)
1473: @cindex printing character
1474: 
1475:   Most characters are @dfn{printing characters}: when they appear in a
1476: buffer, they are displayed literally on the screen.  Printing
1477: characters include @acronym{ASCII} numbers, letters, and punctuation
1478: characters, as well as many non-@acronym{ASCII} characters.
1479: 
1480: @vindex tab-width
1481: @cindex control characters on display
1482:   The @acronym{ASCII} character set contains non-printing @dfn{control
1483: characters}.  Two of these are displayed specially: the newline
1484: character (Unicode code point @code{U+000A}) is displayed by starting
1485: a new line, while the tab character (@code{U+0009}) is displayed as a
1486: space that extends to the next tab stop column (normally every 8
1487: columns).  The number of spaces per tab is controlled by the
1488: buffer-local variable @code{tab-width}, which must have an integer
1489: value between 1 and 1000, inclusive.  Note that how the tab character
1490: in the buffer is displayed has nothing to do with the definition of
1491: @key{TAB} as a command.
1492: 
1493:   Other @acronym{ASCII} control characters, whose codes are below
1494: @code{U+0020} (octal 40, decimal 32), are displayed as a caret
1495: (@samp{^}) followed by the non-control version of the character, with
1496: the @code{escape-glyph} face.  For instance, the @samp{control-A}
1497: character, @code{U+0001}, is displayed as @samp{^A}.
1498: 
1499: @cindex octal escapes
1500: @vindex ctl-arrow
1501:   The raw bytes with codes @code{U+0080} (octal 200) through
1502: @code{U+009F} (octal 237) are displayed as @dfn{octal escape
1503: sequences}, with the @code{escape-glyph} face.  For instance,
1504: character code @code{U+0098} (octal 230) is displayed as @samp{\230}.
1505: If you change the buffer-local variable @code{ctl-arrow} to
1506: @code{nil}, the @acronym{ASCII} control characters are also displayed
1507: as octal escape sequences instead of caret escape sequences.
1508: 
1509: @vindex nobreak-char-display
1510: @cindex non-breaking space
1511: @cindex non-breaking hyphen
1512: @cindex soft hyphen
1513: @cindex @code{escape-glyph} face
1514: @cindex @code{nobreak-space} face
1515:   Some non-@acronym{ASCII} characters have the same appearance as an
1516: @acronym{ASCII} space or hyphen (minus) character.  Such characters
1517: can cause problems if they are entered into a buffer without your
1518: realization, e.g., by yanking; for instance, source code compilers
1519: typically do not treat non-@acronym{ASCII} spaces as whitespace
1520: characters.  To deal with this problem, Emacs displays such characters
1521: specially: it displays @code{U+00A0} (no-break space) with the
1522: @code{nobreak-space} face, and it displays @code{U+00AD} (soft
1523: hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking
1524: hyphen) with the @code{nobreak-hyphen} face.  To disable this, change
1525: the variable @code{nobreak-char-display} to @code{nil}.  If you give
1526: this variable a non-@code{nil} and non-@code{t} value, Emacs instead
1527: displays such characters as a highlighted backslash followed by a
1528: space or hyphen.
1529: 
1530:   You can customize the way any particular character code is displayed
1531: by means of a display table.  @xref{Display Tables,, Display Tables,
1532: elisp, The Emacs Lisp Reference Manual}.
1533: 
1534: @cindex glyphless characters
1535: @cindex characters with no font glyphs
1536: @cindex @code{glyphless-char} face
1537:   On graphical displays, some characters may have no glyphs in any of
1538: the fonts available to Emacs.  These @dfn{glyphless characters} are
1539: normally displayed as boxes containing the hexadecimal character code.
1540: Similarly, on text terminals, characters that cannot be displayed
1541: using the terminal encoding (@pxref{Terminal Coding}) are normally
1542: displayed as question signs.  You can control the display method by
1543: customizing the variable @code{glyphless-char-display-control}.  You
1544: can also customize the @code{glyphless-char} face to make these
1545: characters more prominent on display.  @xref{Glyphless Chars,,
1546: Glyphless Character Display, elisp, The Emacs Lisp Reference Manual},
1547: for details.
1548: 
1549: @cindex curly quotes, and terminal capabilities
1550: @cindex curved quotes, and terminal capabilities
1551: @cindex @code{homoglyph} face
1552: 
1553: Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
1554: can be displayed on the current display.  By default, if this seems to
1555: be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
1556: and @samp{'}), when they appear in messages and help texts, to these
1557: curved quotes.  You can influence or inhibit this translation by
1558: customizing the user option @code{text-quoting-style} (@pxref{Keys in
1559: Documentation,,, elisp, The Emacs Lisp Reference Manual}).
1560: 
1561:   If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
1562: known to look just like @acronym{ASCII} characters, they are shown
1563: with the @code{homoglyph} face.  Curved quotes that are known not to
1564: be displayable are shown as their @acronym{ASCII} approximations
1565: @samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face.
1566: 
1567: @node Cursor Display
1568: @section Displaying the Cursor
1569: @cindex text cursor
1570: 
1571: @vindex visible-cursor
1572:   On a text terminal, the cursor's appearance is controlled by the
1573: terminal, largely out of the control of Emacs.  Some terminals offer
1574: two different cursors: a visible static cursor, and a very
1575: visible blinking cursor.  By default, Emacs uses the very visible
1576: cursor, and switches to it when you start or resume Emacs.  If the
1577: variable @code{visible-cursor} is @code{nil} when Emacs starts or
1578: resumes, it uses the normal cursor.
1579: 
1580: @vindex cursor-type
1581:   On a graphical display, many more properties of the text cursor can
1582: be altered.  To customize its color, change the @code{:background}
1583: attribute of the face named @code{cursor} (@pxref{Face
1584: Customization}).  (The other attributes of this face have no effect;
1585: the text shown under the cursor is drawn using the frame's background
1586: color.)  To change its shape, customize the buffer-local variable
1587: @code{cursor-type}; possible values are @code{box} (the default),
1588: @code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar
1589: . @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a
1590: horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n}
1591: pixels tall), or @code{nil} (no cursor at all).
1592: 
1593: @findex blink-cursor-mode
1594: @cindex cursor, blinking
1595: @cindex blinking cursor
1596: @vindex blink-cursor-mode
1597: @vindex blink-cursor-blinks
1598: @vindex blink-cursor-alist
1599:   By default, the cursor stops blinking after 10 blinks, if Emacs does
1600: not get any input during that time; any input event restarts the
1601: count.  You can customize the variable @code{blink-cursor-blinks} to
1602: control that: its value says how many times to blink without input
1603: before stopping.  Setting that variable to a zero or negative value
1604: will make the cursor blink forever.  To disable cursor blinking
1605: altogether, change the variable @code{blink-cursor-mode} to @code{nil}
1606: (@pxref{Easy Customization}), or add the line
1607: 
1608: @lisp
1609:   (blink-cursor-mode 0)
1610: @end lisp
1611: 
1612: @noindent
1613: to your init file.  Alternatively, you can change how the cursor
1614: looks when it blinks off by customizing the list variable
1615: @code{blink-cursor-alist}.  Each element in the list should have the
1616: form @code{(@var{on-type} . @var{off-type})}; this means that if the
1617: cursor is displayed as @var{on-type} when it blinks on (where
1618: @var{on-type} is one of the cursor types described above), then it is
1619: displayed as @var{off-type} when it blinks off.
1620: 
1621: @vindex x-stretch-cursor
1622: @cindex wide block cursor
1623:   Some characters, such as tab characters, are extra wide.  When
1624: the cursor is positioned over such a character, it is normally drawn
1625: with the default character width.  You can make the cursor stretch to
1626: cover wide characters, by changing the variable
1627: @code{x-stretch-cursor} to a non-@code{nil} value.
1628: 
1629: @cindex cursor in non-selected windows
1630: @vindex cursor-in-non-selected-windows
1631:   The cursor normally appears in non-selected windows as a
1632: non-blinking hollow box.  (For a bar cursor, it instead appears as a
1633: thinner bar.)  To turn off cursors in non-selected windows, change the
1634: variable @code{cursor-in-non-selected-windows} to @code{nil}.
1635: 
1636: @findex hl-line-mode
1637: @findex global-hl-line-mode
1638: @cindex highlight current line
1639:   To make the cursor even more visible, you can use HL Line mode, a
1640: minor mode that highlights the line containing point.  Use @kbd{M-x
1641: hl-line-mode} to enable or disable it in the current buffer.  @kbd{M-x
1642: global-hl-line-mode} enables or disables the same mode globally.
1643: 
1644: @node Line Truncation
1645: @section Line Truncation
1646: 
1647: @cindex truncation
1648: @cindex line truncation
1649:   As an alternative to continuation (@pxref{Continuation Lines}),
1650: Emacs can display long lines by @dfn{truncation}.  This means that all
1651: the characters that do not fit in the width of the screen or window do
1652: not appear at all.  On graphical displays, a small straight arrow in
1653: the fringe indicates truncation at either end of the line.  On text
1654: terminals, this is indicated with @samp{$} signs in the rightmost
1655: and/or leftmost columns.
1656: 
1657: @vindex truncate-lines
1658: @findex toggle-truncate-lines
1659:   Horizontal scrolling automatically causes line truncation
1660: (@pxref{Horizontal Scrolling}).  You can explicitly enable line
1661: truncation for a particular buffer with the command @kbd{M-x
1662: toggle-truncate-lines}.  This works by locally changing the variable
1663: @code{truncate-lines}.  If that variable is non-@code{nil}, long lines
1664: are truncated; if it is @code{nil}, they are continued onto multiple
1665: screen lines.  Setting the variable @code{truncate-lines} in any way
1666: makes it local to the current buffer; until that time, the default
1667: value, which is normally @code{nil}, is in effect.
1668: 
1669:   If a split window becomes too narrow, Emacs may automatically enable
1670: line truncation.  @xref{Split Window}, for the variable
1671: @code{truncate-partial-width-windows} which controls this.
1672: 
1673: @node Visual Line Mode
1674: @section Visual Line Mode
1675: 
1676: @cindex word wrap
1677:   Another alternative to ordinary line continuation is to use
1678: @dfn{word wrap}.  Here, each long logical line is divided into two or
1679: more screen lines, like in ordinary line continuation.  However, Emacs
1680: attempts to wrap the line at word boundaries near the right window
1681: edge.  (If the line's direction is right-to-left, it is wrapped at the
1682: left window edge instead.)  This makes the text easier to read, as
1683: wrapping does not occur in the middle of words.
1684: 
1685: @cindex mode, Visual Line
1686: @cindex Visual Line mode
1687: @findex visual-line-mode
1688: @findex global-visual-line-mode
1689:   Word wrap is enabled by Visual Line mode, an optional minor mode.
1690: To turn on Visual Line mode in the current buffer, type @kbd{M-x
1691: visual-line-mode}; repeating this command turns it off.  You can also
1692: turn on Visual Line mode using the menu bar: in the Options menu,
1693: select the @samp{Line Wrapping in this Buffer} submenu, followed by
1694: the @samp{Word Wrap (Visual Line mode)} menu item.  While Visual Line
1695: mode is enabled, the mode line shows the string @samp{wrap} in the
1696: mode display.  The command @kbd{M-x global-visual-line-mode} toggles
1697: Visual Line mode in all buffers.
1698: 
1699: @findex beginning-of-visual-line
1700: @findex end-of-visual-line
1701: @findex next-logical-line
1702: @findex previous-logical-line
1703:   In Visual Line mode, some editing commands work on screen lines
1704: instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line})
1705: moves to the beginning of the screen line, @kbd{C-e}
1706: (@code{end-of-visual-line}) moves to the end of the screen line, and
1707: @kbd{C-k} (@code{kill-visual-line}) kills text to the end of the
1708: screen line.
1709: 
1710:   To move by logical lines, use the commands @kbd{M-x
1711: next-logical-line} and @kbd{M-x previous-logical-line}.  These move
1712: point to the next logical line and the previous logical line
1713: respectively, regardless of whether Visual Line mode is enabled.  If
1714: you use these commands frequently, it may be convenient to assign key
1715: bindings to them.  @xref{Init Rebinding}.
1716: 
1717:   By default, word-wrapped lines do not display fringe indicators.
1718: Visual Line mode is often used to edit files that contain many long
1719: logical lines, so having a fringe indicator for each wrapped line
1720: would be visually distracting.  You can change this by customizing the
1721: variable @code{visual-line-fringe-indicators}.
1722: 
1723: @node Display Custom
1724: @section Customization of Display
1725: 
1726:   This section describes variables that control miscellaneous aspects
1727: of the appearance of the Emacs screen.  Beginning users can skip it.
1728: 
1729: @vindex display-line-numbers
1730: @cindex number lines in a buffer
1731: @cindex display line numbers
1732:   If you want to have Emacs display line numbers for every line in the
1733: buffer, customize the buffer-local variable
1734: @code{display-line-numbers}; it is @code{nil} by default.  This
1735: variable can have several different values to support various modes of
1736: line-number display:
1737: 
1738: @table @asis
1739: @item @code{t}
1740: Display (an absolute) line number before each non-continuation screen
1741: line that displays buffer text.  If the line is a continuation line,
1742: or if the entire screen line displays a display or an overlay string,
1743: that line will not be numbered.
1744: 
1745: @item @code{relative}
1746: Display relative line numbers before non-continuation lines which show
1747: buffer text.  The line numbers are relative to the line showing point,
1748: so the numbers grow both up and down as lines become farther from the
1749: current line.
1750: 
1751: @item @code{visual}
1752: This value causes Emacs to count lines visually: only lines actually
1753: shown on the display will be counted (disregarding any lines in
1754: invisible parts of text), and lines which wrap to consume more than
1755: one screen line will be numbered that many times.  The displayed
1756: numbers are relative, as with @code{relative} value above.  This is
1757: handy in modes that fold text, such as Outline mode (@pxref{Outline
1758: Mode}), and when you need to move by exact number of screen lines.
1759: 
1760: @item anything else
1761: Any other non-@code{nil} value is treated as @code{t}.
1762: @end table
1763: 
1764: @findex display-line-numbers-mode
1765: @findex global-display-line-numbers-mode
1766: @vindex display-line-numbers-type
1767: The command @kbd{M-x display-line-numbers-mode} provides a
1768: convenient way to turn on display of line numbers.  This mode has a globalized
1769: variant, @code{global-display-line-numbers-mode}.  The user option
1770: @code{display-line-numbers-type} controls which sub-mode of
1771: line-number display, described above, will these modes activate.
1772: 
1773: @noindent
1774: Note that line numbers are not displayed in the minibuffer and in the
1775: tooltips, even if you turn on @code{display-line-numbers-mode}
1776: globally.
1777: 
1778: @vindex display-line-numbers-current-absolute
1779: When Emacs displays relative line numbers, you can control the number
1780: displayed before the current line, the line showing point.  By
1781: default, Emacs displays the absolute number of the current line there,
1782: even though all the other line numbers are relative.  If you customize
1783: the variable @code{display-line-numbers-current-absolute} to a
1784: @code{nil} value, the number displayed for the current line will be
1785: zero.  This is handy if you don't care about the number of the current
1786: line, and want to leave more horizontal space for text in large
1787: buffers.
1788: 
1789: @vindex display-line-numbers-widen
1790: In a narrowed buffer (@pxref{Narrowing}) lines are normally numbered
1791: starting at the beginning of the narrowing.  However, if you customize
1792: the variable @code{display-line-numbers-widen} to a non-@code{nil}
1793: value, line numbers will disregard any narrowing and will start at the
1794: first character of the buffer.
1795: 
1796: @vindex display-line-numbers-width-start
1797: @vindex display-line-numbers-grow-only
1798: @vindex display-line-numbers-width
1799: In selective display mode (@pxref{Selective Display}), and other modes
1800: that hide many lines from display (such as Outline and Org modes), you
1801: may wish to customize the variables
1802: @code{display-line-numbers-width-start} and
1803: @code{display-line-numbers-grow-only}, or set
1804: @code{display-line-numbers-width} to a large enough value, to avoid
1805: occasional miscalculations of space reserved for the line numbers.
1806: 
1807: @cindex @code{line-number} face
1808: The line numbers are displayed in a special face @code{line-number}.
1809: The current line number is displayed in a different face,
1810: @code{line-number-current-line}, so you can make the current line's
1811: number have a distinct appearance, which will help locating the line
1812: showing point.
1813: 
1814: @vindex visible-bell
1815:   If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
1816: to make the whole screen blink when it would normally make an audible bell
1817: sound.  This variable has no effect if your terminal does not have a way
1818: to make the screen blink.
1819: 
1820: @vindex echo-keystrokes
1821:   The variable @code{echo-keystrokes} controls the echoing of multi-character
1822: keys; its value is the number of seconds of pause required to cause echoing
1823: to start, or zero, meaning don't echo at all.  The value takes effect when
1824: there is something to echo.  @xref{Echo Area}.
1825: 
1826: @cindex mouse pointer
1827: @cindex hourglass pointer display
1828: @vindex display-hourglass
1829: @vindex hourglass-delay
1830:   On graphical displays, Emacs displays the mouse pointer as an
1831: hourglass if Emacs is busy.  To disable this feature, set the variable
1832: @code{display-hourglass} to @code{nil}.  The variable
1833: @code{hourglass-delay} determines the number of seconds of busy
1834: time before the hourglass is shown; the default is 1.
1835: 
1836: @vindex make-pointer-invisible
1837:   If the mouse pointer lies inside an Emacs frame, Emacs makes it
1838: invisible each time you type a character to insert text, to prevent it
1839: from obscuring the text.  (To be precise, the hiding occurs when you
1840: type a self-inserting character.  @xref{Inserting Text}.)  Moving
1841: the mouse pointer makes it visible again.  To disable this feature,
1842: set the variable @code{make-pointer-invisible} to @code{nil}.
1843: 
1844: @vindex underline-minimum-offset
1845: @vindex x-underline-at-descent-line
1846:   On graphical displays, the variable @code{underline-minimum-offset}
1847: determines the minimum distance between the baseline and underline, in
1848: pixels, for underlined text.  By default, the value is 1; increasing
1849: it may improve the legibility of underlined text for certain fonts.
1850: (However, Emacs will never draw the underline below the current line
1851: area.)  The variable @code{x-underline-at-descent-line} determines how
1852: to draw underlined text.  The default is @code{nil}, which means to
1853: draw it at the baseline level of the font; if you change it to
1854: @code{t}, Emacs draws the underline at the same height as the font's
1855: descent line.  (If non-default line spacing was specified for the
1856: underlined text, see @ref{Line Height,,, elisp, The Emacs Lisp
1857: Reference Manual}, Emacs draws the underline below the additional
1858: spacing.)
1859: 
1860: @vindex overline-margin
1861:   The variable @code{overline-margin} specifies the vertical position
1862: of an overline above the text, including the height of the overline
1863: itself, in pixels; the default is 2.
1864: 
1865: @findex tty-suppress-bold-inverse-default-colors
1866:   On some text terminals, bold face and inverse video together result
1867: in text that is hard to read.  Call the function
1868: @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
1869: argument to suppress the effect of bold-face in this case.
1870: 
1871: @vindex display-raw-bytes-as-hex
1872:   Raw bytes are displayed in octal format by default, for example a
1873: byte with a decimal value of 128 is displayed as @code{\200}.  To
1874: change display to the hexadecimal format of @code{\x80}, set the
1875: variable @code{display-raw-bytes-as-hex} to @code{t}.
1876: