0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 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
0978: for a face use @kbd{M-n} and @kbd{M-p} to cycle through them.
0979: 
0980: @vindex hi-lock-auto-select-face
0981: Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil}
0982: value causes this command (and other Hi Lock commands that read faces)
0983: to automatically choose the next face from the default list without
0984: prompting.
0985: 
0986: You can use this command multiple times, specifying various regular
0987: expressions to highlight in different ways.
0988: 
0989: @item M-s h u @var{regexp} @key{RET}
0990: @itemx C-x w r @var{regexp} @key{RET}
0991: @kindex M-s h u
0992: @kindex C-x w r
0993: @findex unhighlight-regexp
0994: Unhighlight @var{regexp} (@code{unhighlight-regexp}).  If you invoke
0995: this from the menu, you select the expression to unhighlight from a
0996: list.  If you invoke this from the keyboard, you use the minibuffer.
0997: It will show the most recently added regular expression; use @kbd{M-n}
0998: to show the next older expression and @kbd{M-p} to select the next
0999: newer expression.  (You can also type the expression by hand, with
1000: completion.)  When the expression you want to unhighlight appears in
1001: the minibuffer, press @kbd{@key{RET}} to exit the minibuffer and
1002: unhighlight it.
1003: 
1004: @item M-s h l @var{regexp} @key{RET} @var{face} @key{RET}
1005: @itemx C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
1006: @kindex M-s h l
1007: @kindex C-x w l
1008: @findex highlight-lines-matching-regexp
1009: @cindex lines, highlighting
1010: @cindex highlighting lines of text
1011: Highlight entire lines containing a match for @var{regexp}, using face
1012: @var{face} (@code{highlight-lines-matching-regexp}).
1013: 
1014: @item M-s h p @var{phrase} @key{RET} @var{face} @key{RET}
1015: @itemx C-x w p @var{phrase} @key{RET} @var{face} @key{RET}
1016: @kindex M-s h p
1017: @kindex C-x w p
1018: @findex highlight-phrase
1019: @cindex phrase, highlighting
1020: @cindex highlighting phrase
1021: Highlight matches of @var{phrase}, using face @var{face}
1022: (@code{highlight-phrase}).  @var{phrase} can be any regexp,
1023: but spaces will be replaced by matches to whitespace and
1024: initial lower-case letters will become case insensitive.
1025: 
1026: @item M-s h .
1027: @itemx C-x w .
1028: @kindex M-s h .
1029: @kindex C-x w .
1030: @findex highlight-symbol-at-point
1031: @cindex symbol, highlighting
1032: @cindex highlighting symbol at point
1033: Highlight the symbol found near point, using the next available face
1034: (@code{highlight-symbol-at-point}).
1035: 
1036: @item M-s h w
1037: @itemx C-x w b
1038: @kindex M-s h w
1039: @kindex C-x w b
1040: @findex hi-lock-write-interactive-patterns
1041: Insert all the current highlighting regexp/face pairs into the buffer
1042: at point, with comment delimiters to prevent them from changing your
1043: program.  (This key binding runs the
1044: @code{hi-lock-write-interactive-patterns} command.)
1045: 
1046: These patterns are extracted from the comments, if appropriate, if you
1047: invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while
1048: Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}).
1049: 
1050: @item M-s h f
1051: @itemx C-x w i
1052: @kindex M-s h f
1053: @kindex C-x w i
1054: @findex hi-lock-find-patterns
1055: Extract regexp/face pairs from comments in the current buffer
1056: (@code{hi-lock-find-patterns}).  Thus, you can enter patterns
1057: interactively with @code{highlight-regexp}, store them into the file
1058: with @code{hi-lock-write-interactive-patterns}, edit them (perhaps
1059: including different faces for different parenthesized parts of the
1060: match), and finally use this command (@code{hi-lock-find-patterns}) to
1061: have Hi Lock highlight the edited patterns.
1062: 
1063: @vindex hi-lock-file-patterns-policy
1064: The variable @code{hi-lock-file-patterns-policy} controls whether Hi
1065: Lock mode should automatically extract and highlight patterns found in a
1066: file when it is visited.  Its value can be @code{nil} (never highlight),
1067: @code{ask} (query the user), or a function.  If it is a function,
1068: @code{hi-lock-find-patterns} calls it with the patterns as argument; if
1069: the function returns non-@code{nil}, the patterns are used.  The default
1070: is @code{ask}.  Note that patterns are always highlighted if you call
1071: @code{hi-lock-find-patterns} directly, regardless of the value of this
1072: variable.
1073: 
1074: @vindex hi-lock-exclude-modes
1075: Also, @code{hi-lock-find-patterns} does nothing if the current major
1076: mode's symbol is a member of the list @code{hi-lock-exclude-modes}.
1077: @end table
1078: 
1079: @node Fringes
1080: @section Window Fringes
1081: @cindex fringes
1082: 
1083: @findex set-fringe-style
1084: @findex fringe-mode
1085: @vindex fringe-mode @r{(variable)}
1086:   On graphical displays, each Emacs window normally has narrow
1087: @dfn{fringes} on the left and right edges.  The fringes are used to
1088: display symbols that provide information about the text in the window.
1089: You can type @kbd{M-x fringe-mode} to toggle display of the fringes or
1090: to modify their width.  This command affects fringes in all frames; to
1091: modify fringes on the selected frame only, use @kbd{M-x
1092: set-fringe-style}.  You can make your changes to the fringes permanent
1093: by customizing the variable @code{fringe-mode}.
1094: 
1095:   The most common use of the fringes is to indicate a continuation
1096: line (@pxref{Continuation Lines}).  When one line of text is split
1097: into multiple screen lines, the left fringe shows a curving arrow for
1098: each screen line except the first, indicating that this is not the
1099: real beginning.  The right fringe shows a curving arrow for each
1100: screen line except the last, indicating that this is not the real
1101: end.  If the line's direction is right-to-left (@pxref{Bidirectional
1102: Editing}), the meanings of the curving arrows in the fringes are
1103: swapped.
1104: 
1105:   The fringes indicate line truncation (@pxref{Line Truncation}) with
1106: short horizontal arrows meaning there's more text on this line which
1107: is scrolled horizontally out of view.  Clicking the mouse on one of
1108: the arrows scrolls the display horizontally in the direction of the
1109: arrow.
1110: 
1111:   The fringes can also indicate other things, such as buffer
1112: boundaries (@pxref{Displaying Boundaries}), and where a program you
1113: are debugging is executing (@pxref{Debuggers}).
1114: 
1115: @vindex overflow-newline-into-fringe
1116:   The fringe is also used for drawing the cursor, if the current line
1117: is exactly as wide as the window and point is at the end of the line.
1118: To disable this, change the variable
1119: @code{overflow-newline-into-fringe} to @code{nil}; this causes Emacs
1120: to continue or truncate lines that are exactly as wide as the window.
1121: 
1122:   If you customize @code{fringe-mode} to remove the fringes on one or
1123: both sides of the window display, the features that display on the
1124: fringe are not available.  Indicators of line continuation and
1125: truncation are an exception: when fringes are not available, Emacs
1126: uses the leftmost and rightmost character cells to indicate
1127: continuation and truncation with special ASCII characters, see
1128: @ref{Continuation Lines}, and @ref{Line Truncation}.  This reduces the
1129: width available for displaying text on each line, because the
1130: character cells used for truncation and continuation indicators are
1131: reserved for that purpose.  Since buffer text can include
1132: bidirectional text, and thus both left-to-right and right-to-left
1133: paragraphs (@pxref{Bidirectional Editing}), removing only one of the
1134: fringes still reserves two character cells, one on each side of the
1135: window, for truncation and continuation indicators, because these
1136: indicators are displayed on opposite sides of the window in
1137: right-to-left paragraphs.
1138: 
1139: @node Displaying Boundaries
1140: @section Displaying Boundaries
1141: 
1142: @vindex indicate-buffer-boundaries
1143:   On graphical displays, Emacs can indicate the buffer boundaries in
1144: the fringes.  If you enable this feature, the first line and the last
1145: line are marked with angle images in the fringes.  This can be
1146: combined with up and down arrow images which say whether it is
1147: possible to scroll the window.
1148: 
1149:   The buffer-local variable @code{indicate-buffer-boundaries} controls
1150: how the buffer boundaries and window scrolling is indicated in the
1151: fringes.  If the value is @code{left} or @code{right}, both angle and
1152: arrow bitmaps are displayed in the left or right fringe, respectively.
1153: 
1154:   If value is an alist (@pxref{Association Lists,,, elisp, the Emacs
1155: Lisp Reference Manual}), each element @code{(@var{indicator} .
1156: @var{position})} specifies the position of one of the indicators.  The
1157: @var{indicator} must be one of @code{top}, @code{bottom}, @code{up},
1158: @code{down}, or @code{t} which specifies the default position for the
1159: indicators not present in the alist.  The @var{position} is one of
1160: @code{left}, @code{right}, or @code{nil} which specifies not to show
1161: this indicator.
1162: 
1163:   For example, @code{((top . left) (t . right))} places the top angle
1164: bitmap in left fringe, the bottom angle bitmap in right fringe, and
1165: both arrow bitmaps in right fringe.  To show just the angle bitmaps in
1166: the left fringe, but no arrow bitmaps, use @code{((top .  left)
1167: (bottom . left))}.
1168: 
1169: @node Useless Whitespace
1170: @section Useless Whitespace
1171: 
1172: @cindex trailing whitespace
1173: @cindex whitespace, trailing
1174: @vindex show-trailing-whitespace
1175:   It is easy to leave unnecessary spaces at the end of a line, or
1176: empty lines at the end of a buffer, without realizing it.  In most
1177: cases, this @dfn{trailing whitespace} has no effect, but sometimes it
1178: can be a nuisance.
1179: 
1180: @cindex @code{trailing-whitespace} face
1181:   You can make trailing whitespace at the end of a line visible by
1182: setting the buffer-local variable @code{show-trailing-whitespace} to
1183: @code{t}.  Then Emacs displays trailing whitespace, using the face
1184: @code{trailing-whitespace}.
1185: 
1186:   This feature does not apply when point is at the end of the line
1187: containing the whitespace.  Strictly speaking, that is trailing
1188: whitespace nonetheless, but displaying it specially in that case
1189: looks ugly while you are typing in new text.  In this special case,
1190: the location of point is enough to show you that the spaces are
1191: present.
1192: 
1193: @findex delete-trailing-whitespace
1194: @vindex delete-trailing-lines
1195:   Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
1196: whitespace.  This command deletes all extra spaces at the end of each
1197: line in the buffer, and all empty lines at the end of the buffer; to
1198: ignore the latter, change the variable @code{delete-trailing-lines} to
1199: @code{nil}.  If the region is active, the command instead deletes
1200: extra spaces at the end of each line in the region.
1201: 
1202: @vindex indicate-empty-lines
1203: @cindex unused lines
1204: @cindex fringes, and unused line indication
1205:   On graphical displays, Emacs can indicate unused lines at the end of
1206: the window with a small image in the left fringe (@pxref{Fringes}).
1207: The image appears for screen lines that do not correspond to any
1208: buffer text, so blank lines at the end of the buffer stand out because
1209: they lack this image.  To enable this feature, set the buffer-local
1210: variable @code{indicate-empty-lines} to a non-@code{nil} value.  You
1211: can enable or disable this feature for all new buffers by setting the
1212: default value of this variable, e.g., @code{(setq-default
1213: indicate-empty-lines t)}.
1214: 
1215: @cindex Whitespace mode
1216: @cindex mode, Whitespace
1217: @findex whitespace-mode
1218: @vindex whitespace-style
1219: @findex whitespace-toggle-options
1220:   Whitespace mode is a buffer-local minor mode that lets you
1221: visualize many kinds of whitespace in the buffer, by either
1222: drawing the whitespace characters with a special face or displaying
1223: them as special glyphs.  To toggle this mode, type @kbd{M-x
1224: whitespace-mode}.  The kinds of whitespace visualized are determined
1225: by the list variable @code{whitespace-style}.  Individual elements in
1226: that list can be toggled on or off in the current buffer by typing
1227: @w{@kbd{M-x whitespace-toggle-options}}.  Here is a partial list
1228: of possible elements (see the variable's documentation for the full
1229: list):
1230: 
1231: @table @code
1232: @item face
1233: Enable all visualizations which use special faces.  This element has a
1234: special meaning: if it is absent from the list, none of the other
1235: visualizations take effect except @code{space-mark}, @code{tab-mark},
1236: and @code{newline-mark}.
1237: 
1238: @item trailing
1239: Highlight trailing whitespace.
1240: 
1241: @item tabs
1242: Highlight tab characters.
1243: 
1244: @item spaces
1245: Highlight space and non-breaking space characters.
1246: 
1247: @item lines
1248: @vindex whitespace-line-column
1249: Highlight lines longer than 80 columns.  To change the column limit,
1250: customize the variable @code{whitespace-line-column}.
1251: 
1252: @item newline
1253: Highlight newlines.
1254: 
1255: @item empty
1256: Highlight empty lines at the beginning and/or end of the buffer.
1257: 
1258: @item big-indent
1259: @vindex whitespace-big-indent-regexp
1260: Highlight too-deep indentation.  By default any sequence of at least 4
1261: consecutive tab characters or 32 consecutive space characters is
1262: highlighted.  To change that, customize the regular expression
1263: @code{whitespace-big-indent-regexp}.
1264: 
1265: @item space-mark
1266: Draw space and non-breaking characters with a special glyph.
1267: 
1268: @item tab-mark
1269: Draw tab characters with a special glyph.
1270: 
1271: @item newline-mark
1272: Draw newline characters with a special glyph.
1273: @end table
1274: 
1275: @findex global-whitespace-toggle-options
1276: @findex global-whitespace-mode
1277: Global Whitespace mode is a global minor mode that lets you visualize
1278: whitespace in all buffers.  To toggle individual features, use
1279: @kbd{M-x global-whitespace-toggle-options}.
1280: 
1281: @node Selective Display
1282: @section Selective Display
1283: @cindex selective display
1284: @findex set-selective-display
1285: @kindex C-x $
1286: 
1287:   Emacs has the ability to hide lines indented more than a given
1288: number of columns.  You can use this to get an overview of a part of a
1289: program.
1290: 
1291:   To hide lines in the current buffer, type @kbd{C-x $}
1292: (@code{set-selective-display}) with a numeric argument @var{n}.  Then
1293: lines with at least @var{n} columns of indentation disappear from the
1294: screen.  The only indication of their presence is that three dots
1295: (@samp{@dots{}}) appear at the end of each visible line that is
1296: followed by one or more hidden ones.
1297: 
1298:   The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
1299: if they were not there.
1300: 
1301:   The hidden lines are still present in the buffer, and most editing
1302: commands see them as usual, so you may find point in the middle of the
1303: hidden text.  When this happens, the cursor appears at the end of the
1304: previous line, after the three dots.  If point is at the end of the
1305: visible line, before the newline that ends it, the cursor appears before
1306: the three dots.
1307: 
1308:   To make all lines visible again, type @kbd{C-x $} with no argument.
1309: 
1310: @vindex selective-display-ellipses
1311:   If you set the variable @code{selective-display-ellipses} to
1312: @code{nil}, the three dots do not appear at the end of a line that
1313: precedes hidden lines.  Then there is no visible indication of the
1314: hidden lines.  This variable becomes local automatically when set.
1315: 
1316:   See also @ref{Outline Mode} for another way to hide part of
1317: the text in a buffer.
1318: 
1319: @node Optional Mode Line
1320: @section Optional Mode Line Features
1321: 
1322: @cindex buffer size display
1323: @cindex display of buffer size
1324: @findex size-indication-mode
1325:   The buffer percentage @var{pos} indicates the percentage of the
1326: buffer above the top of the window.  You can additionally display the
1327: size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
1328: Size Indication mode.  The size will be displayed immediately
1329: following the buffer percentage like this:
1330: 
1331: @example
1332: @var{pos} of @var{size}
1333: @end example
1334: 
1335: @noindent
1336: Here @var{size} is the human readable representation of the number of
1337: characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
1338: for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
1339: 
1340: @cindex line number display
1341: @cindex display of current line number
1342: @findex line-number-mode
1343:   The current line number of point appears in the mode line when Line
1344: Number mode is enabled.  Use the command @kbd{M-x line-number-mode} to
1345: turn this mode on and off; normally it is on.  The line number appears
1346: after the buffer percentage @var{pos}, with the letter @samp{L} to
1347: indicate what it is.
1348: 
1349: @cindex Column Number mode
1350: @cindex mode, Column Number
1351: @findex column-number-mode
1352:   Similarly, you can display the current column number by turning on
1353: Column Number mode with @kbd{M-x column-number-mode}.  The column
1354: number is indicated by the letter @samp{C}.  However, when both of
1355: these modes are enabled, the line and column numbers are displayed in
1356: parentheses, the line number first, rather than with @samp{L} and
1357: @samp{C}.  For example: @samp{(561,2)}.  @xref{Minor Modes}, for more
1358: information about minor modes and about how to use these commands.
1359: 
1360: @vindex column-number-indicator-zero-based
1361:   In Column Number mode, the displayed column number counts from zero
1362: starting at the left margin of the window.  If you would prefer for
1363: the displayed column number to count from one, you may set
1364: @code{column-number-indicator-zero-based} to @code{nil}.
1365: 
1366: @cindex narrowing, and line number display
1367:   If you have narrowed the buffer (@pxref{Narrowing}), the displayed
1368: line number is relative to the accessible portion of the buffer.
1369: Thus, it isn't suitable as an argument to @code{goto-line}.  (Use
1370: @code{what-line} command to see the line number relative to the whole
1371: file.)
1372: 
1373: @vindex line-number-display-limit
1374:   If the buffer is very large (larger than the value of
1375: @code{line-number-display-limit}), Emacs won't compute the line
1376: number, because that would be too slow; therefore, the line number
1377: won't appear on the mode-line.  To remove this limit, set
1378: @code{line-number-display-limit} to @code{nil}.
1379: 
1380: @vindex line-number-display-limit-width
1381:   Line-number computation can also be slow if the lines in the buffer
1382: are too long.  For this reason, Emacs doesn't display line numbers if
1383: the average width, in characters, of lines near point is larger than
1384: the value of @code{line-number-display-limit-width}.  The default
1385: value is 200 characters.
1386: 
1387: @findex display-time
1388: @cindex time (on mode line)
1389:   Emacs can optionally display the time and system load in all mode
1390: lines.  To enable this feature, type @kbd{M-x display-time} or customize
1391: the option @code{display-time-mode}.  The information added to the mode
1392: line looks like this:
1393: 
1394: @example
1395: @var{hh}:@var{mm}PM @var{l.ll}
1396: @end example
1397: 
1398: @noindent
1399: @vindex display-time-24hr-format
1400: Here @var{hh} and @var{mm} are the hour and minute, followed always by
1401: @samp{AM} or @samp{PM}.  @var{l.ll} is the average number, collected
1402: for the last few minutes, of processes in the whole system that were
1403: either running or ready to run (i.e., were waiting for an available
1404: processor).  (Some fields may be missing if your operating system
1405: cannot support them.)  If you prefer time display in 24-hour format,
1406: set the variable @code{display-time-24hr-format} to @code{t}.
1407: 
1408: @cindex mail (on mode line)
1409: @vindex display-time-use-mail-icon
1410: @vindex display-time-mail-face
1411: @vindex display-time-mail-file
1412: @vindex display-time-mail-directory
1413:   The word @samp{Mail} appears after the load level if there is mail
1414: for you that you have not read yet.  On graphical displays, you can
1415: use an icon instead of @samp{Mail} by customizing
1416: @code{display-time-use-mail-icon}; this may save some space on the
1417: mode line.  You can customize @code{display-time-mail-face} to make
1418: the mail indicator prominent.  Use @code{display-time-mail-file} to
1419: specify the mail file to check, or set
1420: @code{display-time-mail-directory} to specify the directory to check
1421: for incoming mail (any nonempty regular file in the directory is
1422: considered to be newly arrived mail).
1423: 
1424: @cindex battery status (on mode line)
1425: @findex display-battery-mode
1426: @vindex display-battery-mode
1427: @vindex battery-mode-line-format
1428:   When running Emacs on a laptop computer, you can display the battery
1429: charge on the mode-line, by using the command
1430: @code{display-battery-mode} or customizing the variable
1431: @code{display-battery-mode}.  The variable
1432: @code{battery-mode-line-format} determines the way the battery charge
1433: is displayed; the exact mode-line message depends on the operating
1434: system, and it usually shows the current battery charge as a
1435: percentage of the total charge.
1436: 
1437: @cindex mode line, 3D appearance
1438: @cindex attributes of mode line, changing
1439: @cindex non-integral number of lines in a window
1440:   On graphical displays, the mode line is drawn as a 3D box.  If you
1441: don't like this effect, you can disable it by customizing the
1442: @code{mode-line} face and setting its @code{box} attribute to
1443: @code{nil}.  @xref{Face Customization}.
1444: 
1445: @cindex non-selected windows, mode line appearance
1446:   By default, the mode line of nonselected windows is displayed in a
1447: different face, called @code{mode-line-inactive}.  Only the selected
1448: window is displayed in the @code{mode-line} face.  This helps show
1449: which window is selected.  When the minibuffer is selected, since
1450: it has no mode line, the window from which you activated the minibuffer
1451: has its mode line displayed using @code{mode-line}; as a result,
1452: ordinary entry to the minibuffer does not change any mode lines.
1453: 
1454: @vindex mode-line-in-non-selected-windows
1455:   You can disable use of @code{mode-line-inactive} by setting variable
1456: @code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
1457: lines are displayed in the @code{mode-line} face.
1458: 
1459: @vindex eol-mnemonic-unix
1460: @vindex eol-mnemonic-dos
1461: @vindex eol-mnemonic-mac
1462: @vindex eol-mnemonic-undecided
1463:   You can customize the mode line display for each of the end-of-line
1464: formats by setting each of the variables @code{eol-mnemonic-unix},
1465: @code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and
1466: @code{eol-mnemonic-undecided} to the strings you prefer.
1467: 
1468: @node Text Display
1469: @section How Text Is Displayed
1470: @cindex characters (in text)
1471: @cindex printing character
1472: 
1473:   Most characters are @dfn{printing characters}: when they appear in a
1474: buffer, they are displayed literally on the screen.  Printing
1475: characters include @acronym{ASCII} numbers, letters, and punctuation
1476: characters, as well as many non-@acronym{ASCII} characters.
1477: 
1478: @vindex tab-width
1479: @cindex control characters on display
1480:   The @acronym{ASCII} character set contains non-printing @dfn{control
1481: characters}.  Two of these are displayed specially: the newline
1482: character (Unicode code point @code{U+000A}) is displayed by starting
1483: a new line, while the tab character (@code{U+0009}) is displayed as a
1484: space that extends to the next tab stop column (normally every 8
1485: columns).  The number of spaces per tab is controlled by the
1486: buffer-local variable @code{tab-width}, which must have an integer
1487: value between 1 and 1000, inclusive.  Note that how the tab character
1488: in the buffer is displayed has nothing to do with the definition of
1489: @key{TAB} as a command.
1490: 
1491:   Other @acronym{ASCII} control characters, whose codes are below
1492: @code{U+0020} (octal 40, decimal 32), are displayed as a caret
1493: (@samp{^}) followed by the non-control version of the character, with
1494: the @code{escape-glyph} face.  For instance, the @samp{control-A}
1495: character, @code{U+0001}, is displayed as @samp{^A}.
1496: 
1497: @cindex octal escapes
1498: @vindex ctl-arrow
1499:   The raw bytes with codes @code{U+0080} (octal 200) through
1500: @code{U+009F} (octal 237) are displayed as @dfn{octal escape
1501: sequences}, with the @code{escape-glyph} face.  For instance,
1502: character code @code{U+0098} (octal 230) is displayed as @samp{\230}.
1503: If you change the buffer-local variable @code{ctl-arrow} to
1504: @code{nil}, the @acronym{ASCII} control characters are also displayed
1505: as octal escape sequences instead of caret escape sequences.
1506: 
1507: @vindex nobreak-char-display
1508: @cindex non-breaking space
1509: @cindex non-breaking hyphen
1510: @cindex soft hyphen
1511: @cindex @code{escape-glyph} face
1512: @cindex @code{nobreak-space} face
1513:   Some non-@acronym{ASCII} characters have the same appearance as an
1514: @acronym{ASCII} space or hyphen (minus) character.  Such characters
1515: can cause problems if they are entered into a buffer without your
1516: realization, e.g., by yanking; for instance, source code compilers
1517: typically do not treat non-@acronym{ASCII} spaces as whitespace
1518: characters.  To deal with this problem, Emacs displays such characters
1519: specially: it displays @code{U+00A0} (no-break space) with the
1520: @code{nobreak-space} face, and it displays @code{U+00AD} (soft
1521: hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking
1522: hyphen) with the @code{nobreak-hyphen} face.  To disable this, change
1523: the variable @code{nobreak-char-display} to @code{nil}.  If you give
1524: this variable a non-@code{nil} and non-@code{t} value, Emacs instead
1525: displays such characters as a highlighted backslash followed by a
1526: space or hyphen.
1527: 
1528:   You can customize the way any particular character code is displayed
1529: by means of a display table.  @xref{Display Tables,, Display Tables,
1530: elisp, The Emacs Lisp Reference Manual}.
1531: 
1532: @cindex glyphless characters
1533: @cindex characters with no font glyphs
1534: @cindex @code{glyphless-char} face
1535:   On graphical displays, some characters may have no glyphs in any of
1536: the fonts available to Emacs.  These @dfn{glyphless characters} are
1537: normally displayed as boxes containing the hexadecimal character code.
1538: Similarly, on text terminals, characters that cannot be displayed
1539: using the terminal encoding (@pxref{Terminal Coding}) are normally
1540: displayed as question signs.  You can control the display method by
1541: customizing the variable @code{glyphless-char-display-control}.  You
1542: can also customize the @code{glyphless-char} face to make these
1543: characters more prominent on display.  @xref{Glyphless Chars,,
1544: Glyphless Character Display, elisp, The Emacs Lisp Reference Manual},
1545: for details.
1546: 
1547: @cindex curly quotes, and terminal capabilities
1548: @cindex curved quotes, and terminal capabilities
1549: @cindex @code{homoglyph} face
1550: 
1551: Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
1552: can be displayed on the current display.  By default, if this seems to
1553: be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
1554: and @samp{'}), when they appear in messages and help texts, to these
1555: curved quotes.  You can influence or inhibit this translation by
1556: customizing the user option @code{text-quoting-style} (@pxref{Keys in
1557: Documentation,,, elisp, The Emacs Lisp Reference Manual}).
1558: 
1559:   If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
1560: known to look just like @acronym{ASCII} characters, they are shown
1561: with the @code{homoglyph} face.  Curved quotes that are known not to
1562: be displayable are shown as their @acronym{ASCII} approximations
1563: @samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face.
1564: 
1565: @node Cursor Display
1566: @section Displaying the Cursor
1567: @cindex text cursor
1568: 
1569: @vindex visible-cursor
1570:   On a text terminal, the cursor's appearance is controlled by the
1571: terminal, largely out of the control of Emacs.  Some terminals offer
1572: two different cursors: a visible static cursor, and a very
1573: visible blinking cursor.  By default, Emacs uses the very visible
1574: cursor, and switches to it when you start or resume Emacs.  If the
1575: variable @code{visible-cursor} is @code{nil} when Emacs starts or
1576: resumes, it uses the normal cursor.
1577: 
1578: @vindex cursor-type
1579:   On a graphical display, many more properties of the text cursor can
1580: be altered.  To customize its color, change the @code{:background}
1581: attribute of the face named @code{cursor} (@pxref{Face
1582: Customization}).  (The other attributes of this face have no effect;
1583: the text shown under the cursor is drawn using the frame's background
1584: color.)  To change its shape, customize the buffer-local variable
1585: @code{cursor-type}; possible values are @code{box} (the default),
1586: @code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar
1587: . @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a
1588: horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n}
1589: pixels tall), or @code{nil} (no cursor at all).
1590: 
1591: @findex blink-cursor-mode
1592: @cindex cursor, blinking
1593: @cindex blinking cursor
1594: @vindex blink-cursor-mode
1595: @vindex blink-cursor-blinks
1596: @vindex blink-cursor-alist
1597:   By default, the cursor stops blinking after 10 blinks, if Emacs does
1598: not get any input during that time; any input event restarts the
1599: count.  You can customize the variable @code{blink-cursor-blinks} to
1600: control that: its value says how many times to blink without input
1601: before stopping.  Setting that variable to a zero or negative value
1602: will make the cursor blink forever.  To disable cursor blinking
1603: altogether, change the variable @code{blink-cursor-mode} to @code{nil}
1604: (@pxref{Easy Customization}), or add the line
1605: 
1606: @lisp
1607:   (blink-cursor-mode 0)
1608: @end lisp
1609: 
1610: @noindent
1611: to your init file.  Alternatively, you can change how the cursor
1612: looks when it blinks off by customizing the list variable
1613: @code{blink-cursor-alist}.  Each element in the list should have the
1614: form @code{(@var{on-type} . @var{off-type})}; this means that if the
1615: cursor is displayed as @var{on-type} when it blinks on (where
1616: @var{on-type} is one of the cursor types described above), then it is
1617: displayed as @var{off-type} when it blinks off.
1618: 
1619: @vindex x-stretch-cursor
1620: @cindex wide block cursor
1621:   Some characters, such as tab characters, are extra wide.  When
1622: the cursor is positioned over such a character, it is normally drawn
1623: with the default character width.  You can make the cursor stretch to
1624: cover wide characters, by changing the variable
1625: @code{x-stretch-cursor} to a non-@code{nil} value.
1626: 
1627: @cindex cursor in non-selected windows
1628: @vindex cursor-in-non-selected-windows
1629:   The cursor normally appears in non-selected windows as a
1630: non-blinking hollow box.  (For a bar cursor, it instead appears as a
1631: thinner bar.)  To turn off cursors in non-selected windows, change the
1632: variable @code{cursor-in-non-selected-windows} to @code{nil}.
1633: 
1634: @findex hl-line-mode
1635: @findex global-hl-line-mode
1636: @cindex highlight current line
1637:   To make the cursor even more visible, you can use HL Line mode, a
1638: minor mode that highlights the line containing point.  Use @kbd{M-x
1639: hl-line-mode} to enable or disable it in the current buffer.  @kbd{M-x
1640: global-hl-line-mode} enables or disables the same mode globally.
1641: 
1642: @node Line Truncation
1643: @section Line Truncation
1644: 
1645: @cindex truncation
1646: @cindex line truncation
1647:   As an alternative to continuation (@pxref{Continuation Lines}),
1648: Emacs can display long lines by @dfn{truncation}.  This means that all
1649: the characters that do not fit in the width of the screen or window do
1650: not appear at all.  On graphical displays, a small straight arrow in
1651: the fringe indicates truncation at either end of the line.  On text
1652: terminals, this is indicated with @samp{$} signs in the rightmost
1653: and/or leftmost columns.
1654: 
1655: @vindex truncate-lines
1656: @findex toggle-truncate-lines
1657:   Horizontal scrolling automatically causes line truncation
1658: (@pxref{Horizontal Scrolling}).  You can explicitly enable line
1659: truncation for a particular buffer with the command @kbd{M-x
1660: toggle-truncate-lines}.  This works by locally changing the variable
1661: @code{truncate-lines}.  If that variable is non-@code{nil}, long lines
1662: are truncated; if it is @code{nil}, they are continued onto multiple
1663: screen lines.  Setting the variable @code{truncate-lines} in any way
1664: makes it local to the current buffer; until that time, the default
1665: value, which is normally @code{nil}, is in effect.
1666: 
1667:   If a split window becomes too narrow, Emacs may automatically enable
1668: line truncation.  @xref{Split Window}, for the variable
1669: @code{truncate-partial-width-windows} which controls this.
1670: 
1671: @node Visual Line Mode
1672: @section Visual Line Mode
1673: 
1674: @cindex word wrap
1675:   Another alternative to ordinary line continuation is to use
1676: @dfn{word wrap}.  Here, each long logical line is divided into two or
1677: more screen lines, like in ordinary line continuation.  However, Emacs
1678: attempts to wrap the line at word boundaries near the right window
1679: edge.  (If the line's direction is right-to-left, it is wrapped at the
1680: left window edge instead.)  This makes the text easier to read, as
1681: wrapping does not occur in the middle of words.
1682: 
1683: @cindex mode, Visual Line
1684: @cindex Visual Line mode
1685: @findex visual-line-mode
1686: @findex global-visual-line-mode
1687:   Word wrap is enabled by Visual Line mode, an optional minor mode.
1688: To turn on Visual Line mode in the current buffer, type @kbd{M-x
1689: visual-line-mode}; repeating this command turns it off.  You can also
1690: turn on Visual Line mode using the menu bar: in the Options menu,
1691: select the @samp{Line Wrapping in this Buffer} submenu, followed by
1692: the @samp{Word Wrap (Visual Line mode)} menu item.  While Visual Line
1693: mode is enabled, the mode line shows the string @samp{wrap} in the
1694: mode display.  The command @kbd{M-x global-visual-line-mode} toggles
1695: Visual Line mode in all buffers.
1696: 
1697: @findex beginning-of-visual-line
1698: @findex end-of-visual-line
1699: @findex next-logical-line
1700: @findex previous-logical-line
1701:   In Visual Line mode, some editing commands work on screen lines
1702: instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line})
1703: moves to the beginning of the screen line, @kbd{C-e}
1704: (@code{end-of-visual-line}) moves to the end of the screen line, and
1705: @kbd{C-k} (@code{kill-visual-line}) kills text to the end of the
1706: screen line.
1707: 
1708:   To move by logical lines, use the commands @kbd{M-x
1709: next-logical-line} and @kbd{M-x previous-logical-line}.  These move
1710: point to the next logical line and the previous logical line
1711: respectively, regardless of whether Visual Line mode is enabled.  If
1712: you use these commands frequently, it may be convenient to assign key
1713: bindings to them.  @xref{Init Rebinding}.
1714: 
1715:   By default, word-wrapped lines do not display fringe indicators.
1716: Visual Line mode is often used to edit files that contain many long
1717: logical lines, so having a fringe indicator for each wrapped line
1718: would be visually distracting.  You can change this by customizing the
1719: variable @code{visual-line-fringe-indicators}.
1720: 
1721: @node Display Custom
1722: @section Customization of Display
1723: 
1724:   This section describes variables that control miscellaneous aspects
1725: of the appearance of the Emacs screen.  Beginning users can skip it.
1726: 
1727: @vindex display-line-numbers
1728: @cindex number lines in a buffer
1729: @cindex display line numbers
1730:   If you want to have Emacs display line numbers for every line in the
1731: buffer, customize the buffer-local variable
1732: @code{display-line-numbers}; it is @code{nil} by default.  This
1733: variable can have several different values to support various modes of
1734: line-number display:
1735: 
1736: @table @asis
1737: @item @code{t}
1738: Display (an absolute) line number before each non-continuation screen
1739: line that displays buffer text.  If the line is a continuation line,
1740: or if the entire screen line displays a display or an overlay string,
1741: that line will not be numbered.
1742: 
1743: @item @code{relative}
1744: Display relative line numbers before non-continuation lines which show
1745: buffer text.  The line numbers are relative to the line showing point,
1746: so the numbers grow both up and down as lines become farther from the
1747: current line.
1748: 
1749: @item @code{visual}
1750: This value causes Emacs to count lines visually: only lines actually
1751: shown on the display will be counted (disregarding any lines in
1752: invisible parts of text), and lines which wrap to consume more than
1753: one screen line will be numbered that many times.  The displayed
1754: numbers are relative, as with @code{relative} value above.  This is
1755: handy in modes that fold text, such as Outline mode (@pxref{Outline
1756: Mode}), and when you need to move by exact number of screen lines.
1757: 
1758: @item anything else
1759: Any other non-@code{nil} value is treated as @code{t}.
1760: @end table
1761: 
1762: @findex display-line-numbers-mode
1763: @findex global-display-line-numbers-mode
1764: @vindex display-line-numbers-type
1765: The command @kbd{M-x display-line-numbers-mode} provides a
1766: convenient way to turn on display of line numbers.  This mode has a globalized
1767: variant, @code{global-display-line-numbers-mode}.  The user option
1768: @code{display-line-numbers-type} controls which sub-mode of
1769: line-number display, described above, will these modes activate.
1770: 
1771: @noindent
1772: Note that line numbers are not displayed in the minibuffer and in the
1773: tooltips, even if you turn on @code{display-line-numbers-mode}
1774: globally.
1775: 
1776: @vindex display-line-numbers-current-absolute
1777: When Emacs displays relative line numbers, you can control the number
1778: displayed before the current line, the line showing point.  By
1779: default, Emacs displays the absolute number of the current line there,
1780: even though all the other line numbers are relative.  If you customize
1781: the variable @code{display-line-numbers-current-absolute} to a
1782: @code{nil} value, the number displayed for the current line will be
1783: zero.  This is handy if you don't care about the number of the current
1784: line, and want to leave more horizontal space for text in large
1785: buffers.
1786: 
1787: @vindex display-line-numbers-widen
1788: In a narrowed buffer (@pxref{Narrowing}) lines are normally numbered
1789: starting at the beginning of the narrowing.  However, if you customize
1790: the variable @code{display-line-numbers-widen} to a non-@code{nil}
1791: value, line numbers will disregard any narrowing and will start at the
1792: first character of the buffer.
1793: 
1794: @vindex display-line-numbers-width-start
1795: @vindex display-line-numbers-grow-only
1796: @vindex display-line-numbers-width
1797: In selective display mode (@pxref{Selective Display}), and other modes
1798: that hide many lines from display (such as Outline and Org modes), you
1799: may wish to customize the variables
1800: @code{display-line-numbers-width-start} and
1801: @code{display-line-numbers-grow-only}, or set
1802: @code{display-line-numbers-width} to a large enough value, to avoid
1803: occasional miscalculations of space reserved for the line numbers.
1804: 
1805: @cindex @code{line-number} face
1806: The line numbers are displayed in a special face @code{line-number}.
1807: The current line number is displayed in a different face,
1808: @code{line-number-current-line}, so you can make the current line's
1809: number have a distinct appearance, which will help locating the line
1810: showing point.
1811: 
1812: @vindex visible-bell
1813:   If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
1814: to make the whole screen blink when it would normally make an audible bell
1815: sound.  This variable has no effect if your terminal does not have a way
1816: to make the screen blink.
1817: 
1818: @vindex echo-keystrokes
1819:   The variable @code{echo-keystrokes} controls the echoing of multi-character
1820: keys; its value is the number of seconds of pause required to cause echoing
1821: to start, or zero, meaning don't echo at all.  The value takes effect when
1822: there is something to echo.  @xref{Echo Area}.
1823: 
1824: @cindex mouse pointer
1825: @cindex hourglass pointer display
1826: @vindex display-hourglass
1827: @vindex hourglass-delay
1828:   On graphical displays, Emacs displays the mouse pointer as an
1829: hourglass if Emacs is busy.  To disable this feature, set the variable
1830: @code{display-hourglass} to @code{nil}.  The variable
1831: @code{hourglass-delay} determines the number of seconds of busy
1832: time before the hourglass is shown; the default is 1.
1833: 
1834: @vindex make-pointer-invisible
1835:   If the mouse pointer lies inside an Emacs frame, Emacs makes it
1836: invisible each time you type a character to insert text, to prevent it
1837: from obscuring the text.  (To be precise, the hiding occurs when you
1838: type a self-inserting character.  @xref{Inserting Text}.)  Moving
1839: the mouse pointer makes it visible again.  To disable this feature,
1840: set the variable @code{make-pointer-invisible} to @code{nil}.
1841: 
1842: @vindex underline-minimum-offset
1843: @vindex x-underline-at-descent-line
1844:   On graphical displays, the variable @code{underline-minimum-offset}
1845: determines the minimum distance between the baseline and underline, in
1846: pixels, for underlined text.  By default, the value is 1; increasing
1847: it may improve the legibility of underlined text for certain fonts.
1848: (However, Emacs will never draw the underline below the current line
1849: area.)  The variable @code{x-underline-at-descent-line} determines how
1850: to draw underlined text.  The default is @code{nil}, which means to
1851: draw it at the baseline level of the font; if you change it to
1852: @code{t}, Emacs draws the underline at the same height as the font's
1853: descent line.  (If non-default line spacing was specified for the
1854: underlined text, see @ref{Line Height,,, elisp, The Emacs Lisp
1855: Reference Manual}, Emacs draws the underline below the additional
1856: spacing.)
1857: 
1858: @vindex overline-margin
1859:   The variable @code{overline-margin} specifies the vertical position
1860: of an overline above the text, including the height of the overline
1861: itself, in pixels; the default is 2.
1862: 
1863: @findex tty-suppress-bold-inverse-default-colors
1864:   On some text terminals, bold face and inverse video together result
1865: in text that is hard to read.  Call the function
1866: @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
1867: argument to suppress the effect of bold-face in this case.
1868: 
1869: @vindex display-raw-bytes-as-hex
1870:   Raw bytes are displayed in octal format by default, for example a
1871: byte with a decimal value of 128 is displayed as @code{\200}.  To
1872: change display to the hexadecimal format of @code{\x80}, set the
1873: variable @code{display-raw-bytes-as-hex} to @code{t}.
1874: