@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Display, Search, Registers, Top
+@node Display
@chapter Controlling the Display
- Since only part of a large buffer fits in the window, Emacs tries to
-show a part that is likely to be interesting. Display-control
-commands and variables allow you to specify which part of the text you
-want to see, and how to display it.
+ Since only part of a large buffer fits in the window, Emacs has to
+show only a part of it. This chapter describes commands and variables
+that let you specify which part of the text you want to see, and how
+the text is displayed.
@menu
* Scrolling:: Commands to move text up and down in a window.
+* Recentering:: A scroll command that centers the current line.
* Auto Scrolling:: Redisplay scrolls text automatically when needed.
* Horizontal Scrolling:: Moving text left and right in a window.
+* Narrowing:: Restricting display and editing to a portion
+ of the buffer.
+* View Mode:: Viewing read-only buffers.
* Follow Mode:: Follow mode lets two windows scroll as one.
* Faces:: How to change the display style using faces.
-* Standard Faces:: Emacs' predefined faces.
-* Temporary Face Changes:: Commands to temporarily modify the default text face
+* Colors:: Specifying colors for faces.
+* Standard Faces:: The main predefined faces.
+* Text Scale:: Increasing or decreasing text size in a buffer.
* Font Lock:: Minor mode for syntactic highlighting using faces.
* Highlight Interactively:: Tell Emacs what text to highlight.
* Fringes:: Enabling or disabling window fringes.
* Displaying Boundaries:: Displaying top and bottom of the buffer.
-* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
+* Useless Whitespace:: Showing possibly spurious trailing whitespace.
* Selective Display:: Hiding lines with lots of indentation.
* Optional Mode Line:: Optional mode line display features.
* Text Display:: How text characters are normally displayed.
@node Scrolling
@section Scrolling
+@cindex scrolling
- If a buffer contains text that is too large to fit entirely within a
-window that is displaying the buffer, Emacs shows a contiguous portion of
-the text. The portion shown always contains point.
+ If a window is too small to display all the text in its buffer, it
+displays only a portion of it. @dfn{Scrolling} commands change which
+portion of the buffer is displayed.
-@cindex scrolling
- @dfn{Scrolling} means moving text up or down in the window so that
-different parts of the text are visible. Scrolling ``forward'' or
-``up'' means that text moves up, and new text appears at the bottom.
-Scrolling ``backward'' or ``down'' moves text down, and new text
-appears at the top.
+ Scrolling ``forward'' or ``up'' advances the portion of the buffer
+displayed in the window; equivalently, it moves the buffer text
+upwards relative to the window. Scrolling ``backward'' or ``down''
+displays an earlier portion of the buffer, and moves the text
+downwards relative to the window.
- Scrolling happens automatically if you move point past the bottom or
-top of the window. You can also scroll explicitly with these
-commands:
+ In Emacs, scrolling ``up'' or ``down'' refers to the direction that
+the text moves in the window, @emph{not} the direction that the window
+moves relative to the text. This terminology was adopted by Emacs
+before the modern meaning of ``scrolling up'' and ``scrolling down''
+became widespread. Hence, the strange result that @key{PageDown}
+scrolls ``up'' in the Emacs sense.
+
+ The portion of a buffer displayed in a window always contains point.
+If you move point past the bottom or top of the window, scrolling
+occurs automatically to bring it back onscreen (@pxref{Auto
+Scrolling}). You can also scroll explicitly with these commands:
@table @kbd
-@item C-l
-Scroll the selected window so that the current line is the center-most
-text line; on subsequent consecutive invocations, make the current
-line the top-most line, the bottom-most line, and so forth in cyclic
-order; also, maybe redisplay the screen (@code{recenter-top-bottom}).
@item C-v
@itemx @key{next}
@itemx @key{PageDown}
-Scroll forward by nearly a full window (@code{scroll-up}).
+Scroll forward by nearly a full window (@code{scroll-up-command}).
@item M-v
@itemx @key{prior}
@itemx @key{PageUp}
-Scroll backward (@code{scroll-down}).
+Scroll backward (@code{scroll-down-command}).
+@end table
+
+@kindex C-v
+@kindex M-v
+@kindex next
+@kindex prior
+@kindex PageDown
+@kindex PageUp
+@findex scroll-up-command
+@findex scroll-down-command
+ @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
+whole window height. The effect is to take the two lines at the
+bottom of the window and put them at the top, followed by lines that
+were not previously visible. If point was in the text that scrolled
+off the top, it ends up on the window's new topmost line. The
+@key{next} (or @key{PageDown}) key is equivalent to @kbd{C-v}.
+
+ @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar
+way. The @key{prior} (or @key{PageUp}) key is equivalent to
+@kbd{M-v}.
+
+@vindex next-screen-context-lines
+ The number of lines of overlap left by these scroll commands is
+controlled by the variable @code{next-screen-context-lines}, whose
+default value is 2. You can supply the commands with a numeric prefix
+argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave
+point unchanged, so that the text and point move up or down together.
+@kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa.
+
+@vindex scroll-error-top-bottom
+ By default, these commands signal an error (by beeping or flashing
+the screen) if no more scrolling is possible, because the window has
+reached the beginning or end of the buffer. If you change the
+variable @code{scroll-error-top-bottom} to @code{t}, the command moves
+point to the farthest possible position. If point is already there,
+the command signals an error.
+
+@vindex scroll-preserve-screen-position
+@cindex @code{scroll-command} property
+ Some users like scroll commands to keep point at the same screen
+position, so that scrolling back to the same screen conveniently
+returns point to its original position. You can enable this behavior
+via the variable @code{scroll-preserve-screen-position}. If the value
+is @code{t}, Emacs adjusts point to keep the cursor at the same screen
+position whenever a scroll command moves it off-window, rather than
+moving it to the topmost or bottommost line. With any other
+non-@code{nil} value, Emacs adjusts point this way even if the scroll
+command leaves point in the window. This variable affects all the
+scroll commands documented in this section, as well as scrolling with
+the mouse wheel (@pxref{Mouse Commands}); in general, it affects any
+command that has a non-@code{nil} @code{scroll-command} property.
+@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}.
+
+@vindex scroll-up
+@vindex scroll-down
+@findex scroll-up-line
+@findex scroll-down-line
+ The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave
+similarly to @code{scroll-up-command} and @code{scroll-down-command},
+except they do not obey @code{scroll-error-top-bottom}. Prior to
+Emacs 24, these were the default commands for scrolling up and down.
+The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line}
+scroll the current window by one line at a time. If you intend to use
+any of these commands, you might want to give them key bindings
+(@pxref{Init Rebinding}).
+
+@node Recentering
+@section Recentering
+
+@table @kbd
+@item C-l
+Scroll the selected window so the current line is the center-most text
+line; on subsequent consecutive invocations, make the current line the
+top line, the bottom line, and so on in cyclic order. Possibly
+redisplay the screen too (@code{recenter-top-bottom}).
+
+@item M-x recenter
+Scroll the selected window so the current line is the center-most text
+line. Possibly redisplay the screen too.
+
@item C-M-l
Scroll heuristically to bring useful information onto the screen
(@code{reposition-window}).
@kindex C-l
@findex recenter-top-bottom
- @kbd{C-l} (@code{recenter-top-bottom}) is a basic scrolling command.
-It @dfn{recenters} the selected window, scrolling it so that the
-current screen line is exactly in the center of the window, or as
-close to the center as possible.
+ The @kbd{C-l} (@code{recenter-top-bottom}) command @dfn{recenters}
+the selected window, scrolling it so that the current screen line is
+exactly in the center of the window, or as close to the center as
+possible.
Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window
so that point is on the topmost screen line. Typing a third @kbd{C-l}
scrolls the window so that point is on the bottom-most screen line.
-Each successive @kbd{C-l} cycles through these three screen positions.
+Each successive @kbd{C-l} cycles through these three positions.
@vindex recenter-positions
You can change the cycling order by customizing the list variable
@code{recenter-positions}. Each list element should be the symbol
@code{top}, @code{middle}, or @code{bottom}, or a number; an integer
-number means to move the line to the specified screen line, while a
+means to move the line to the specified screen line, while a
floating-point number between 0.0 and 1.0 specifies a percentage of
-the screen space from the top. The default, @code{(middle top
-bottom)}, is the cycling order described above. Furthermore, if you
-change the variable @code{scroll-margin} to a non-zero value @var{n},
-Emacs always leaves @var{n} screen lines between point and the top or
-bottom of the window (@pxref{Auto Scrolling}).
-
- You can also supply @kbd{C-l} with a prefix argument. With a plain
-prefix argument, @kbd{C-u C-l}, Emacs simply recenters point. With a
-positive argument @var{n}, it scrolls to place point @var{n} lines
-down from the top of the window. An argument of zero puts point on
-the topmost line. A negative argument @var{-n} puts point @var{n}
-lines from the bottom of the window. For example, @kbd{C-u - 1 C-l}
-puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five
-lines from the bottom. When given an argument, @kbd{C-l} does not
-clear the screen or cycle through different screen positions.
-
- The more primitive command @code{recenter} behaves like
-@code{recenter-top-bottom}, but does not cycle among screen positions.
-Prior to Emacs 23, @kbd{C-l} was bound to @code{recenter}.
+the screen space from the top of the window. The default,
+@code{(middle top bottom)}, is the cycling order described above.
+Furthermore, if you change the variable @code{scroll-margin} to a
+non-zero value @var{n}, @kbd{C-l} always leaves at least @var{n}
+screen lines between point and the top or bottom of the window
+(@pxref{Auto Scrolling}).
+
+ You can also give @kbd{C-l} a prefix argument. A plain prefix
+argument, @kbd{C-u C-l}, simply recenters point. A positive argument
+@var{n} puts point @var{n} lines down from the top of the window. An
+argument of zero puts point on the topmost line. A negative argument
+@var{-n} puts point @var{n} lines from the bottom of the window. When
+given an argument, @kbd{C-l} does not clear the screen or cycle
+through different screen positions.
@vindex recenter-redisplay
If the variable @code{recenter-redisplay} has a non-@code{nil}
-value, Emacs clears and redisplays the screen each time @kbd{C-l}
-recenters the window; the special value @code{tty} (the default) says
-to do this on text-terminal frames only. Redisplaying is useful in
-case the screen becomes garbled for any reason (@pxref{Screen
-Garbled}).
-
-@kindex C-v
-@kindex M-v
-@kindex next
-@kindex prior
-@kindex PageDown
-@kindex PageUp
-@findex scroll-up
-@findex scroll-down
- To read the buffer a windowful at a time, type @kbd{C-v}
-(@code{scroll-up}). This scrolls forward by nearly the whole window
-height. The effect is to take the two lines at the bottom of the
-window and put them at the top, followed by lines that were not
-previously visible. If point was in the text that scrolled off the
-top, it ends up at the new top of the window.
+value, each invocation of @kbd{C-l} also clears and redisplays the
+screen; the special value @code{tty} (the default) says to do this on
+text-terminal frames only. Redisplaying is useful in case the screen
+becomes garbled for any reason (@pxref{Screen Garbled}).
- @kbd{M-v} (@code{scroll-down}) scrolls backward in a similar way.
-
-@vindex next-screen-context-lines
- The variable @code{next-screen-context-lines} controls the number of
-lines of overlap left by @kbd{C-v} or @kbd{M-v}; by default, it is 2.
-The function keys @key{next} and @key{prior}, or @key{PageDown} and
-@key{PageUp}, are equivalent to @kbd{C-v} and @kbd{M-v} respectively.
-
- You can supply @kbd{C-v} or @kbd{M-v} with a numeric prefix argument
-@var{n}. This scrolls the window by @var{n} lines, while attempting
-to leave point unchanged (so that the text and point move up or down
-together). @kbd{C-v} with a negative argument is like @kbd{M-v} and
-vice versa.
-
- The names of scroll commands are based on the direction that the
-text moves in the window. Thus, the command to scroll forward is
-called @code{scroll-up} because it moves the text upward on the
-screen. The keys @key{PageUp} and @key{PageDown} derive their names
-and customary meanings from a different convention that developed
-elsewhere; hence the strange result that @key{PageDown} runs
-@code{scroll-up}.
-
-@vindex scroll-preserve-screen-position
- Some users like the full-screen scroll commands to keep point at the
-same screen position. To enable this behavior, set the variable
-@code{scroll-preserve-screen-position} to a non-@code{nil} value.
-Then, whenever a command scrolls the text around point offscreen (or
-within @code{scroll-margin} lines of the edge), Emacs moves point to
-keep it at the same vertical and horizontal position within the
-window. This mode is convenient for browsing through a file by
-scrolling by screenfuls; if you come back to the screen where you
-started, point goes back to the line where it started.
+@findex recenter
+ The more primitive command @kbd{M-x recenter} behaves like
+@code{recenter-top-bottom}, but does not cycle among screen positions.
@kindex C-M-l
@findex reposition-window
- The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
-window heuristically in a way designed to get useful information onto
-the screen. For example, in a Lisp file, this command tries to get the
+ @kbd{C-M-l} (@code{reposition-window}) scrolls the current window
+heuristically in a way designed to get useful information onto the
+screen. For example, in a Lisp file, this command tries to get the
entire current defun onto the screen if possible.
@node Auto Scrolling
@cindex aggressive scrolling
@vindex scroll-up-aggressively
@vindex scroll-down-aggressively
- When the window does scroll by a longer distance, you can control
-how aggressively it scrolls by setting the variables
-@code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
-The value of @code{scroll-up-aggressively} should be either
-@code{nil}, or a fraction @var{f} between 0 and 1. A fraction
-specifies where on the screen to put point when scrolling upward,
-i.e.@: when point moves forward in the buffer, and therefore text
-scrolls up in the window. When point goes off the window end, the new
-start position is chosen to put point @var{f} parts of the window
-height from the bottom. Thus, larger @var{f} means more aggressive
-scrolling: more new text is brought into view. The default value,
-@code{nil}, is equivalent to 0.5.
+ When the window does scroll by a distance longer than
+@code{scroll-step}, you can control how aggressively it scrolls by
+setting the variables @code{scroll-up-aggressively} and
+@code{scroll-down-aggressively}. The value of
+@code{scroll-up-aggressively} should be either @code{nil}, or a
+fraction @var{f} between 0 and 1. A fraction specifies where on the
+screen to put point when scrolling upward, i.e.@: forward. When point
+goes off the window end, the new start position is chosen to put point
+@var{f} parts of the window height from the bottom margin. Thus,
+larger @var{f} means more aggressive scrolling: more new text is
+brought into view. The default value, @code{nil}, is equivalent to
+0.5.
Likewise, @code{scroll-down-aggressively} is used for scrolling
-down, i.e.@: moving point back in the buffer. The value specifies how
-far point should be placed from the top of the window; thus, as with
+down, i.e.@: backward. The value specifies how far point should be
+placed from the top margin of the window; thus, as with
@code{scroll-up-aggressively}, a larger value is more aggressive.
These two variables are ignored if either @code{scroll-step} or
@vindex scroll-margin
The variable @code{scroll-margin} restricts how close point can come
-to the top or bottom of a window. Its value is a number of screen
+to the top or bottom of a window (even if aggressive scrolling
+specifies a fraction @var{f} that is larger than the window portion
+between the top and the bottom margins). Its value is a number of screen
lines; if point comes within that many lines of the top or bottom of
the window, Emacs performs automatic scrolling. By default,
@code{scroll-margin} is 0.
screen. To disable automatic horizontal scrolling, set the variable
@code{auto-hscroll-mode} to @code{nil}. Note that when the automatic
horizontal scrolling is turned off, if point moves off the edge of the
-screen, the cursor disappears to indicate that. (On text-mode
-terminals, the cursor is left at the edge instead.)
+screen, the cursor disappears to indicate that. (On text terminals,
+the cursor is left at the edge instead.)
@vindex hscroll-margin
The variable @code{hscroll-margin} controls how close point can get
will continue to scroll the window, but never farther to the right
than the amount you previously set by @code{scroll-left}.
+@node Narrowing
+@section Narrowing
+@cindex widening
+@cindex restriction
+@cindex narrowing
+@cindex accessible portion
+
+ @dfn{Narrowing} means focusing in on some portion of the buffer,
+making the rest temporarily inaccessible. The portion which you can
+still get to is called the @dfn{accessible portion}. Canceling the
+narrowing, which makes the entire buffer once again accessible, is
+called @dfn{widening}. The bounds of narrowing in effect in a buffer
+are called the buffer's @dfn{restriction}.
+
+ Narrowing can make it easier to concentrate on a single subroutine or
+paragraph by eliminating clutter. It can also be used to limit the
+range of operation of a replace command or repeating keyboard macro.
+
+@table @kbd
+@item C-x n n
+Narrow down to between point and mark (@code{narrow-to-region}).
+@item C-x n w
+Widen to make the entire buffer accessible again (@code{widen}).
+@item C-x n p
+Narrow down to the current page (@code{narrow-to-page}).
+@item C-x n d
+Narrow down to the current defun (@code{narrow-to-defun}).
+@end table
+
+ When you have narrowed down to a part of the buffer, that part appears
+to be all there is. You can't see the rest, you can't move into it
+(motion commands won't go outside the accessible part), you can't change
+it in any way. However, it is not gone, and if you save the file all
+the inaccessible text will be saved. The word @samp{Narrow} appears in
+the mode line whenever narrowing is in effect.
+
+@kindex C-x n n
+@findex narrow-to-region
+ The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
+It sets the current buffer's restrictions so that the text in the current
+region remains accessible, but all text before the region or after the
+region is inaccessible. Point and mark do not change.
+
+@kindex C-x n p
+@findex narrow-to-page
+@kindex C-x n d
+@findex narrow-to-defun
+ Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
+down to the current page. @xref{Pages}, for the definition of a page.
+@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
+containing point (@pxref{Defuns}).
+
+@kindex C-x n w
+@findex widen
+ The way to cancel narrowing is to widen with @kbd{C-x n w}
+(@code{widen}). This makes all text in the buffer accessible again.
+
+ You can get information on what part of the buffer you are narrowed down
+to using the @kbd{C-x =} command. @xref{Position Info}.
+
+ Because narrowing can easily confuse users who do not understand it,
+@code{narrow-to-region} is normally a disabled command. Attempting to use
+this command asks for confirmation and gives you the option of enabling it;
+if you enable the command, confirmation will no longer be required for
+it. @xref{Disabling}.
+
+@node View Mode
+@section View Mode
+@cindex View mode
+@cindex mode, View
+
+@kindex s @r{(View mode)}
+@kindex SPC @r{(View mode)}
+@kindex DEL @r{(View mode)}
+ View mode is a minor mode that lets you scan a buffer by sequential
+screenfuls. It provides commands for scrolling through the buffer
+conveniently but not for changing it. Apart from the usual Emacs
+cursor motion commands, you can type @key{SPC} to scroll forward one
+windowful, @key{DEL} to scroll backward, and @kbd{s} to start an
+incremental search.
+
+@kindex q @r{(View mode)}
+@kindex e @r{(View mode)}
+@findex View-quit
+@findex View-exit
+ Typing @kbd{q} (@code{View-quit}) disables View mode, and switches
+back to the buffer and position before View mode was enabled. Typing
+@kbd{e} (@code{View-exit}) disables View mode, keeping the current
+buffer and position.
+
+@findex view-buffer
+@findex view-file
+ @kbd{M-x view-buffer} prompts for an existing Emacs buffer, switches
+to it, and enables View mode. @kbd{M-x view-file} prompts for a file
+and visits it with View mode enabled.
+
@node Follow Mode
@section Follow Mode
@cindex Follow mode
@cindex synchronizing windows
@dfn{Follow mode} is a minor mode that makes two windows, both
-showing the same buffer, scroll as a single tall ``virtual window.''
+showing the same buffer, scroll as a single tall ``virtual window''.
To use Follow mode, go to a frame with just one window, split it into
two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
follow-mode}. From then on, you can edit the buffer in either of the
To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
@node Faces
-@section Faces: Controlling Text Display Style
+@section Text Faces
@cindex faces
- Emacs can display text in several different styles, which are called
+ Emacs can display text in several different styles, called
@dfn{faces}. Each face can specify various @dfn{face attributes},
-such as the font, height, weight and slant, the foreground and
-background color, and underlining or overlining. A face does not have
-to specify all of these attributes; often it inherits most of them
-from another face.
-
- On a text-only terminal, not all face attributes are meaningful.
-Some text-only terminals support inverse video, bold, and underline
-attributes; some support colors. Text-only terminals generally do not
-support changing the height, width or font.
-
- Most major modes assign faces to the text automatically through the
-work of Font Lock mode. @xref{Font Lock}, for more information about
-Font Lock mode and syntactic highlighting. You can print the current
-buffer with the highlighting that appears on your screen using the
-command @code{ps-print-buffer-with-faces}. @xref{PostScript}.
-
- Enriched mode, the mode for editing formatted text, provides
-commands and menus for specifying faces for text in the buffer.
-@xref{Format Faces}.
+such as the font, height, weight, slant, foreground and background
+color, and underlining or overlining. Most major modes assign faces
+to the text automatically, via Font Lock mode. @xref{Font Lock}, for
+more information about how these faces are assigned.
-@cindex face colors, setting
- To alter the appearance of a face, use the customization buffer.
-@xref{Face Customization}. You can also use X resources to specify
-attributes of any particular face (@pxref{Resources}). When
-displaying a character, any attribute that isn't specified by its face
-is taken from the @code{default} face, whose attributes reflect the
-default settings of the frame itself.
+@findex list-faces-display
+ To see what faces are currently defined, and what they look like,
+type @kbd{M-x list-faces-display}. With a prefix argument, this
+prompts for a regular expression, and displays only faces with names
+matching that regular expression (@pxref{Regexps}).
+
+ It's possible for a given face to look different in different
+frames. For instance, some text terminals do not support all face
+attributes, particularly font, height, and width, and some support a
+limited range of colors.
+
+@cindex background color
+@cindex default face
+ You can customize a face to alter its appearance, and save those
+changes for future Emacs sessions. @xref{Face Customization}. A face
+does not have to specify every single attribute; often it inherits
+most attributes from another face. Any ultimately unspecified
+attribute is taken from the face named @code{default}.
+
+ The @code{default} face is the default for displaying text, and all
+of its attributes are specified. Its background color is also used as
+the frame's background color. @xref{Colors}.
+
+@cindex cursor face
+ Another special face is the @code{cursor} face. On graphical
+displays, the background color of this face is used to draw the text
+cursor. None of the other attributes of this face have any effect;
+the foreground color for text under the cursor is taken from the
+background color of the underlying text. On text terminals, the
+appearance of the text cursor is determined by the terminal, not by
+the @code{cursor} face.
+
+ You can also use X resources to specify attributes of any particular
+face. @xref{Resources}.
+
+ Emacs can display variable-width fonts, but some Emacs commands,
+particularly indentation commands, do not account for variable
+character display widths. Therefore, we recommend not using
+variable-width fonts for most faces, particularly those assigned by
+Font Lock mode.
+
+@node Colors
+@section Colors for Faces
+@cindex color name
+@cindex RGB triplet
+
+ Faces can have various foreground and background colors. When you
+specify a color for a face---for instance, when customizing the face
+(@pxref{Face Customization})---you can use either a @dfn{color name}
+or an @dfn{RGB triplet}.
+
+@findex list-colors-display
+@vindex list-colors-sort
+ A color name is a pre-defined name, such as @samp{dark orange} or
+@samp{medium sea green}. To view a list of color names, type @kbd{M-x
+list-colors-display}. To control the order in which colors are shown,
+customize @code{list-colors-sort}. If you run this command on a
+graphical display, it shows the full range of color names known to
+Emacs (these are the standard X11 color names, defined in X's
+@file{rgb.txt} file). If you run the command on a text terminal, it
+shows only a small subset of colors that can be safely displayed on
+such terminals. However, Emacs understands X11 color names even on
+text terminals; if a face is given a color specified by an X11 color
+name, it is displayed using the closest-matching terminal color.
+
+ An RGB triplet is a string of the form @samp{#RRGGBB}. Each of the
+R, G, and B components is a hexadecimal number specifying the
+component's relative intensity, one to four digits long (usually two
+digits are used). The components must have the same number of digits.
+For hexadecimal values A to F, either upper or lower case are
+acceptable.
+
+ The @kbd{M-x list-colors-display} command also shows the equivalent
+RGB triplet for each named color. For instance, @samp{medium sea
+green} is equivalent to @samp{#3CB371}.
+@cindex face colors, setting
@findex set-face-foreground
@findex set-face-background
- You can also change the foreground and background colors of a
-specific face with @kbd{M-x set-face-foreground} and @kbd{M-x
-set-face-background}. These commands prompt in the minibuffer for a
-face name and a color name, with completion, and then set that face to
-use the specified color. @xref{Face Customization}, for information
-about color names. These commands affect the face colors on all
-frames, both existing and those to be created in the future. These
-changes do not, however, persist for future Emacs sessions; to make
-lasting changes, use the customization buffer (@pxref{Face
-Customization}).
-
- You can also set foreground and background colors for the current
-frame only; see @ref{Frame Parameters}.
-
- Emacs can display variable-width fonts, but some of the Emacs
-commands that calculate width and indentation do not know how to
-calculate variable widths. This can sometimes lead to incorrect
-results when you use variable-width fonts. In particular, indentation
-commands can give inconsistent results, so we recommend you avoid
-variable-width fonts, especially for editing program source code.
+ You can change the foreground and background colors of a face with
+@kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
+These commands prompt in the minibuffer for a face name and a color,
+with completion, and then set that face to use the specified color.
+They affect the face colors on all frames, but their effects do not
+persist for future Emacs sessions, unlike using the customization
+buffer or X resources. You can also use frame parameters to set
+foreground and background colors for a specific frame; @xref{Frame
+Parameters}.
@node Standard Faces
@section Standard Faces
-@findex list-faces-display
- To see what faces are currently defined, and what they look like,
-type @kbd{M-x list-faces-display}. It's possible for a given face to
-look different in different frames; this command shows the appearance
-in the frame in which you type it. With a prefix argument, this
-prompts for a regular expression, and displays only faces with names
-matching that regular expression.
-
Here are the standard faces for specifying text appearance. You can
apply them to specific text when you want the effects they produce.
@table @code
@item default
This face is used for ordinary text that doesn't specify any face.
+Its background color is used as the frame's background color.
@item bold
This face uses a bold variant of the default font.
@item italic
@table @code
@item highlight
-This face is used for highlighting portions of text, in various modes.
-For example, mouse-sensitive text is highlighted using this face.
+This face is used for text highlighting in various contexts, such as
+when the mouse cursor is moved over a hyperlink.
@item isearch
-This face is used for highlighting the current Isearch match
+This face is used to highlight the current Isearch match
(@pxref{Incremental Search}).
@item query-replace
-This face is used for highlighting the current Query Replace match
+This face is used to highlight the current Query Replace match
(@pxref{Replace}).
@item lazy-highlight
-This face is used for lazy highlighting of Isearch and Query Replace
-matches other than the current one.
+This face is used to highlight ``lazy matches'' for Isearch and Query
+Replace (matches other than the current one).
@item region
-This face is used for displaying a selected region (@pxref{Mark}).
+This face is used for displaying an active region (@pxref{Mark}).
+When Emacs is built with GTK support, its colors are taken from the
+current GTK theme.
@item secondary-selection
This face is used for displaying a secondary X selection (@pxref{Secondary
Selection}).
@item trailing-whitespace
The face for highlighting excess spaces and tabs at the end of a line
-when @code{show-trailing-whitespace} is non-@code{nil}; see
-@ref{Useless Whitespace}.
-@item nobreak-space
-The face for displaying the character ``nobreak space.''
+when @code{show-trailing-whitespace} is non-@code{nil} (@pxref{Useless
+Whitespace}).
@item escape-glyph
-The face for highlighting the @samp{\} or @samp{^} that indicates
-a control character. It's also used when @samp{\} indicates a
-nobreak space or nobreak (soft) hyphen.
+The face for displaying control characters and escape sequences
+(@pxref{Text Display}).
+@item nobreak-space
+The face for displaying ``no-break'' space characters (@pxref{Text
+Display}).
@end table
- These faces control the appearance of parts of the Emacs frame.
-They exist as faces to provide a consistent way to customize the
-appearance of these parts of the frame.
+ The following faces control the appearance of parts of the Emacs
+frame:
@table @code
@item mode-line
Most windows do not have a header line---only some special modes, such
Info mode, create one.
@item vertical-border
-This face is used for the vertical divider between windows.
-By default this face inherits from the @code{mode-line-inactive} face
-on character terminals. On graphical displays the foreground color of
-this face is used for the vertical line between windows without
-scrollbars.
+This face is used for the vertical divider between windows on text
+terminals.
@item minibuffer-prompt
@cindex @code{minibuffer-prompt} face
@vindex minibuffer-prompt-properties
displays. (The fringes are the narrow portions of the Emacs frame
between the text area and the window's right and left borders.)
@xref{Fringes}.
-@item scroll-bar
-This face determines the visual appearance of the scroll bar.
-@xref{Scroll Bars}.
-@item border
-This face determines the color of the frame border.
@item cursor
-This face determines the color of the cursor.
+The @code{:background} attribute of this face specifies the color of
+the text cursor. @xref{Cursor Display}.
+@item tooltip
+This face is used for tooltip text. By default, if Emacs is built
+with GTK support, tooltips are drawn via GTK and this face has no
+effect. @xref{Tooltips}.
@item mouse
This face determines the color of the mouse pointer.
+@end table
+
+ The following faces likewise control the appearance of parts of the
+Emacs frame, but only on text terminals, or when Emacs is built on X
+with no toolkit support. (For all other cases, the appearance of the
+respective frame elements is determined by system-wide settings.)
+
+@table @code
+@item scroll-bar
+This face determines the visual appearance of the scroll bar.
+@xref{Scroll Bars}.
@item tool-bar
This face determines the color of tool bar icons. @xref{Tool Bars}.
-@item tooltip
-This face is used for tooltips. @xref{Tooltips}.
@item menu
@cindex menu bar appearance
@cindex @code{menu} face, no effect if customized
@cindex customization of @code{menu} face
This face determines the colors and font of Emacs's menus. @xref{Menu
-Bars}. This has no effect in Emacs built with GTK and in the
-MS-Windows/Mac ports; you need to use system-wide styles and options
-to change the appearance of GTK, Windows, or Mac menus. Setting the
-font of LessTif/Motif menus is currently not supported; attempts to
-set the font are ignored in this case.
+Bars}.
@end table
-@node Temporary Face Changes
-@section Temporary Face Changes
-
-The following commands change the default face within a buffer.
+@node Text Scale
+@section Text Scale
@cindex adjust buffer face height
@findex text-scale-adjust
The final key of these commands may be repeated without the leading
@kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face
-height by three steps. Each step scales the height of the default
-face by the value of the variable @code{text-scale-mode-step}. As a
-special case, an argument of 0 removes any scaling currently active.
+height by three steps. Each step scales the text height by a factor
+of 1.2; to change this factor, customize the variable
+@code{text-scale-mode-step}. As an exception, a numeric argument of 0
+to the @code{text-scale-adjust} command restores the default height,
+similar to typing @kbd{C-x C-0}.
@cindex increase buffer face height
@findex text-scale-increase
@cindex set buffer face height
@findex text-scale-set
-The command @code{text-scale-set} sets the height of the default face
-in the current buffer to an absolute level specified by its prefix
-argument.
+ The command @code{text-scale-set} scales the height of the default
+face in the current buffer to an absolute level specified by its
+prefix argument.
@findex text-scale-mode
- The above commands automatically enable or disable the minor mode
-@code{text-scale-mode}, depending on whether the current font scaling
-is other than 1 or not.
-
-@cindex variable pitch mode
-@findex variable-pitch-mode
- To temporarily change the face in the current buffer to a
-variable-pitch (``proportional'') font, use the command @kbd{M-x
-variable-pitch-mode} to enable or disable the Variable Pitch minor
-mode.
+ The above commands automatically enable the minor mode
+@code{text-scale-mode} if the current font scaling is other than 1,
+and disable it otherwise.
@node Font Lock
@section Font Lock mode
@cindex syntax highlighting and coloring
Font Lock mode is a minor mode, always local to a particular buffer,
-which highlights (or ``fontifies'') the buffer contents according to
-the syntax of the text you are editing. It can recognize comments and
-strings in most programming languages; in several languages, it can
-also recognize and properly highlight various other important
-constructs, such as names of functions being defined or reserved
-keywords. Some special modes, such as Occur mode and Info mode, have
-completely specialized ways of assigning fonts for Font Lock mode.
+which assigns faces to (or @dfn{fontifies}) the text in the buffer.
+Each buffer's major mode tells Font Lock mode which text to fontify;
+for instance, programming language modes fontify syntactically
+relevant constructs like comments, strings, and function names.
@findex font-lock-mode
- Font Lock mode is turned on by default in all modes which support it.
-You can toggle font-lock for each buffer with the command @kbd{M-x
-font-lock-mode}. Using a positive argument unconditionally turns Font
-Lock mode on, and a negative or zero argument turns it off.
+ Font Lock mode is enabled by default. To toggle it in the current
+buffer, type @kbd{M-x font-lock-mode}. A positive numeric argument
+unconditionally enables Font Lock mode, and a negative or zero
+argument disables it.
@findex global-font-lock-mode
@vindex global-font-lock-mode
- If you do not wish Font Lock mode to be turned on by default,
-customize the variable @code{global-font-lock-mode} using the Customize
-interface (@pxref{Easy Customization}), or use the function
-@code{global-font-lock-mode} in your @file{.emacs} file, like this:
+ Type @kbd{M-x global-font-lock-mode} to toggle Font Lock mode in all
+buffers. To impose this setting for future Emacs sessions, customize
+the variable @code{global-font-lock-mode} (@pxref{Easy
+Customization}), or add the following line to your init file:
@example
(global-font-lock-mode 0)
@end example
@noindent
-This variable, like all the variables that control Font Lock mode,
-take effect whenever fontification is done; that is, potentially at
-any time.
-
-@findex turn-on-font-lock
- If you have disabled Global Font Lock mode, you can still enable Font
+If you have disabled Global Font Lock mode, you can still enable Font
Lock for specific major modes by adding the function
-@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For
-example, to enable Font Lock mode for editing C files, you can do this:
+@code{font-lock-mode} to the mode hooks (@pxref{Hooks}). For example,
+to enable Font Lock mode for editing C files, you can do this:
@example
-(add-hook 'c-mode-hook 'turn-on-font-lock)
+(add-hook 'c-mode-hook 'font-lock-mode)
@end example
Font Lock mode uses several specifically named faces to do its job,
faces. @xref{Face Customization}.
@vindex font-lock-maximum-decoration
- The variable @code{font-lock-maximum-decoration} specifies the
-preferred level of fontification, for modes that provide multiple
-levels. Level 1 is the least amount of fontification; some modes
-support levels as high as 3. The normal default is ``as high as
-possible.'' You can specify an integer, which applies to all modes, or
-you can specify different numbers for particular major modes; for
-example, to use level 1 for C/C++ modes, and the default level
-otherwise, use this:
+ You can customize the variable @code{font-lock-maximum-decoration}
+to alter the amount of fontification applied by Font Lock mode, for
+major modes that support this feature. The value should be a number
+(with 1 representing a minimal amount of fontification; some modes
+support levels as high as 3); or @code{t}, meaning ``as high as
+possible'' (the default). You can also specify different numbers for
+particular major modes; for example, to use level 1 for C/C++ modes,
+and the default level otherwise, use the value
@example
-(setq font-lock-maximum-decoration
- '((c-mode . 1) (c++-mode . 1)))
+'((c-mode . 1) (c++-mode . 1)))
@end example
-@vindex font-lock-maximum-size
- Fontification can be too slow for large buffers, so you can suppress
-it for buffers above a certain size. The variable
-@code{font-lock-maximum-size} specifies a buffer size, beyond which
-buffer fontification is suppressed.
-
-@c @w is used below to prevent a bad page-break.
@vindex font-lock-beginning-of-syntax-function
@cindex incorrect fontification
@cindex parenthesis in column zero and fontification
relies on analysis of the syntactic structure of the buffer text. For
the sake of speed, some modes, including Lisp mode, rely on a special
convention: an open-parenthesis or open-brace in the leftmost column
-always defines the @w{beginning} of a defun, and is thus always
-outside any string or comment. (@xref{Left Margin Paren}.) If you
-don't follow this convention, Font Lock mode can misfontify the text
-that follows an open-parenthesis or open-brace in the leftmost column
-that is inside a string or comment.
+always defines the beginning of a defun, and is thus always outside
+any string or comment. Therefore, you should avoid placing an
+open-parenthesis or open-brace in the leftmost column, if it is inside
+a string or comment. @xref{Left Margin Paren}, for details.
@cindex slow display during scrolling
The variable @code{font-lock-beginning-of-syntax-function}, which is
are close to the end of a large buffer.
@findex font-lock-add-keywords
- Font Lock highlighting patterns already exist for many modes, but you
-may want to fontify additional patterns. You can use the function
-@code{font-lock-add-keywords}, to add your own highlighting patterns for
-a particular mode. For example, to highlight @samp{FIXME:} words in C
-comments, use this:
+ Font Lock highlighting patterns already exist for most modes, but
+you may want to fontify additional patterns. You can use the function
+@code{font-lock-add-keywords}, to add your own highlighting patterns
+for a particular mode. For example, to highlight @samp{FIXME:} words
+in C comments, use this:
@example
(add-hook 'c-mode-hook
@end example
@findex font-lock-remove-keywords
- To remove keywords from the font-lock highlighting patterns, use the
+@noindent
+To remove keywords from the font-lock highlighting patterns, use the
function @code{font-lock-remove-keywords}. @xref{Search-based
Fontification,,, elisp, The Emacs Lisp Reference Manual}.
@cindex just-in-time (JIT) font-lock
@cindex background syntax highlighting
Fontifying large buffers can take a long time. To avoid large
-delays when a file is visited, Emacs fontifies only the visible
-portion of a buffer. As you scroll through the buffer, each portion
-that becomes visible is fontified as soon as it is displayed; this
-type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT}) Lock.
-You can control how JIT Lock behaves, including telling it to perform
-fontification while idle, by customizing variables in the
+delays when a file is visited, Emacs initially fontifies only the
+visible portion of a buffer. As you scroll through the buffer, each
+portion that becomes visible is fontified as soon as it is displayed;
+this type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT})
+Lock. You can control how JIT Lock behaves, including telling it to
+perform fontification while idle, by customizing variables in the
customization group @samp{jit-lock}. @xref{Specific Customization}.
@node Highlight Interactively
@findex highlight-changes-mode
Highlight Changes mode is a minor mode that @dfn{highlights} the parts
-of the buffer were changed most recently, by giving that text a
+of the buffer that were changed most recently, by giving that text a
different face. To enable or disable Highlight Changes mode, use
@kbd{M-x highlight-changes-mode}.
@section Window Fringes
@cindex fringes
- On a graphical display, each Emacs window normally has narrow
+@findex set-fringe-style
+@findex fringe-mode
+ On graphical displays, each Emacs window normally has narrow
@dfn{fringes} on the left and right edges. The fringes are used to
display symbols that provide information about the text in the window.
+You can type @kbd{M-x fringe-mode} to disable the fringes, or modify
+their width. This command affects fringes in all frames; to modify
+fringes on the selected frame only, use @kbd{M-x set-fringe-style}.
The most common use of the fringes is to indicate a continuation
-line, when one line of text is split into multiple lines on the
-screen. The left fringe shows a curving arrow for each screen line
-except the first, indicating that ``this is not the real beginning.''
-The right fringe shows a curving arrow for each screen line except the
-last, indicating that ``this is not the real end.'' If the line's
-direction is right-to-left (@pxref{Bidirectional Editing}), the
-meaning of the curving arrows in the left and right fringes are
+line (@pxref{Continuation Lines}). When one line of text is split
+into multiple screen lines, the left fringe shows a curving arrow for
+each screen line except the first, indicating that ``this is not the
+real beginning''. The right fringe shows a curving arrow for each
+screen line except the last, indicating that ``this is not the real
+end''. If the line's direction is right-to-left (@pxref{Bidirectional
+Editing}), the meanings of the curving arrows in the fringes are
swapped.
The fringes indicate line truncation with short horizontal arrows
meaning ``there's more text on this line which is scrolled
-horizontally out of view;'' clicking the mouse on one of the arrows
-scrolls the display horizontally in the direction of the arrow. The
-fringes can also indicate other things, such as empty lines, or where a
-program you are debugging is executing (@pxref{Debuggers}).
+horizontally out of view''. Clicking the mouse on one of the arrows
+scrolls the display horizontally in the direction of the arrow.
-@findex set-fringe-style
-@findex fringe-mode
- You can enable and disable the fringes for all frames using
-@kbd{M-x fringe-mode}. To enable and disable the fringes
-for the selected frame, use @kbd{M-x set-fringe-style}.
+ The fringes can also indicate other things, such as buffer
+boundaries (@pxref{Displaying Boundaries}), and where a program you
+are debugging is executing (@pxref{Debuggers}).
+
+@vindex overflow-newline-into-fringe
+ The fringe is also used for drawing the cursor, if the current line
+is exactly as wide as the window and point is at the end of the line.
+To disable this, change the variable
+@code{overflow-newline-into-fringe} to @code{nil}; this causes Emacs
+to continue or truncate lines that are exactly as wide as the window.
@node Displaying Boundaries
@section Displaying Boundaries
@vindex indicate-buffer-boundaries
- On a graphical display, Emacs can indicate the buffer boundaries in
-the fringes. It indicates the first line and the last line with
-angle images in the fringes. This can be combined with up and down
-arrow images which say whether it is possible to scroll the window up
-and down.
+ On graphical displays, Emacs can indicate the buffer boundaries in
+the fringes. If you enable this feature, the first line and the last
+line are marked with angle images in the fringes. This can be
+combined with up and down arrow images which say whether it is
+possible to scroll the window.
The buffer-local variable @code{indicate-buffer-boundaries} controls
how the buffer boundaries and window scrolling is indicated in the
present.
@findex delete-trailing-whitespace
- Type @kbd{M-x delete-trailing-whitespace @key{RET}} to delete all
-trailing whitespace within the buffer's accessible portion
-(@pxref{Narrowing}). This command does not remove newline characters.
+ Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
+whitespace within the buffer. If the region is active, it deletes all
+trailing whitespace in the region instead.
@vindex indicate-empty-lines
@cindex unused lines
@cindex fringes, and unused line indication
- Emacs can indicate unused lines at the end of the window with a
-small image in the left fringe (@pxref{Fringes}). The image appears
-for window lines that do not correspond to any buffer text. Blank
-lines at the end of the buffer then stand out because they do not have
-this image in the fringe.
-
- To enable this feature, set the buffer-local variable
-@code{indicate-empty-lines} to a non-@code{nil} value. You can enable
-or disable this feature for all new buffers by setting the default
-value of this variable, e.g.@: @code{(setq-default
-indicate-empty-lines t)};. (This feature currently doesn't work on
-text-only terminals.)
+ On graphical displays, Emacs can indicate unused lines at the end of
+the window with a small image in the left fringe (@pxref{Fringes}).
+The image appears for screen lines that do not correspond to any
+buffer text, so blank lines at the end of the buffer stand out because
+they lack this image. To enable this feature, set the buffer-local
+variable @code{indicate-empty-lines} to a non-@code{nil} value. You
+can enable or disable this feature for all new buffers by setting the
+default value of this variable, e.g.@: @code{(setq-default
+indicate-empty-lines t)}.
+
+@cindex Whitespace mode
+@cindex mode, Whitespace
+@findex whitespace-mode
+@vindex whitespace-style
+ Whitespace mode is a buffer-local minor mode that lets you
+``visualize'' many kinds of whitespace in the buffer, by either
+drawing the whitespace characters with a special face or displaying
+them as special glyphs. To toggle this mode, type @kbd{M-x
+whitespace-mode}. The kinds of whitespace visualized are determined
+by the list variable @code{whitespace-style}. Here is a partial list
+of possible elements (see the variable's documentation for the full
+list):
+
+@table @code
+@item face
+Enable all visualizations which use special faces. This element has a
+special meaning: if it is absent from the list, none of the other
+visualizations take effect except @code{space-mark}, @code{tab-mark},
+and @code{newline-mark}.
+
+@item trailing
+Highlight trailing whitespace.
+
+@item tabs
+Highlight tab characters.
+
+@item spaces
+Highlight space and non-breaking space characters.
+
+@item lines
+@vindex whitespace-line-column
+Highlight lines longer than 80 lines. To change the column limit,
+customize the variable @code{whitespace-line-column}.
+
+@item newline
+Highlight newlines.
+
+@item empty
+Highlight empty lines.
+
+@item space-mark
+Draw space and non-breaking characters with a special glyph.
+
+@item tab-mark
+Draw tab characters with a special glyph.
+
+@item newline-mark
+Draw newline characters with a special glyph.
+@end table
@node Selective Display
@section Selective Display
@vindex display-time-mail-file
@vindex display-time-mail-directory
The word @samp{Mail} appears after the load level if there is mail
-for you that you have not read yet. On a graphical display you can use
-an icon instead of @samp{Mail} by customizing
-@code{display-time-use-mail-icon}; this may save some space on the mode
-line. You can customize @code{display-time-mail-face} to make the mail
-indicator prominent. Use @code{display-time-mail-file} to specify
-the mail file to check, or set @code{display-time-mail-directory}
-to specify the directory to check for incoming mail (any nonempty regular
-file in the directory is considered as ``newly arrived mail'').
+for you that you have not read yet. On graphical displays, you can
+use an icon instead of @samp{Mail} by customizing
+@code{display-time-use-mail-icon}; this may save some space on the
+mode line. You can customize @code{display-time-mail-face} to make
+the mail indicator prominent. Use @code{display-time-mail-file} to
+specify the mail file to check, or set
+@code{display-time-mail-directory} to specify the directory to check
+for incoming mail (any nonempty regular file in the directory is
+considered as ``newly arrived mail'').
@cindex mail (on mode line)
@findex display-battery-mode
@cindex mode line, 3D appearance
@cindex attributes of mode line, changing
@cindex non-integral number of lines in a window
- By default, the mode line is drawn on graphics displays with
-3D-style highlighting, like that of a button when it is not being
-pressed. If you don't like this effect, you can disable the 3D
-highlighting of the mode line, by customizing the attributes of the
-@code{mode-line} face. @xref{Face Customization}.
+ On graphical displays, the mode line is drawn as a 3D box. If you
+don't like this effect, you can disable it by customizing the
+@code{mode-line} face and setting its @code{box} attribute to
+@code{nil}. @xref{Face Customization}.
@cindex non-selected windows, mode line appearance
By default, the mode line of nonselected windows is displayed in a
@node Text Display
@section How Text Is Displayed
@cindex characters (in text)
+@cindex printing character
- @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs
-buffers are displayed with their graphics, as are non-@acronym{ASCII} multibyte
-printing characters (octal codes above 0400).
+ Most characters are @dfn{printing characters}: when they appear in a
+buffer, they are displayed literally on the screen. Printing
+characters include @acronym{ASCII} numbers, letters, and punctuation
+characters, as well as many non-@acronym{ASCII} characters.
@vindex tab-width
- Some @acronym{ASCII} control characters are displayed in special
-ways. The newline character (octal code 012) is displayed by starting
-a new line. The tab character (octal code 011) is displayed by moving
-to the next tab stop column (normally every 8 columns). The number of
-spaces per tab is controlled by the variable @code{tab-width}, which
-must have an integer value between 1 and 1000, inclusive, and is made
-buffer-local by changing it. Note that how the tab character in the buffer
-is displayed has nothing to do with the definition of @key{TAB} as a
-command.
-
- Other @acronym{ASCII} control characters are normally displayed as a caret
-(@samp{^}) followed by the non-control version of the character; thus,
-control-A is displayed as @samp{^A}. The caret appears in face
-@code{escape-glyph}.
-
- Non-@acronym{ASCII} characters 0200 through 0237 (octal) are
-displayed with octal escape sequences; thus, character code 0230
-(octal) is displayed as @samp{\230}. The backslash appears in face
-@code{escape-glyph}.
-
+@cindex control characters on display
+ The @acronym{ASCII} character set contains non-printing @dfn{control
+characters}. Two of these are displayed specially: the newline
+character (Unicode code point @code{U+000A}) is displayed by starting
+a new line, while the tab character (@code{U+0009}) is displayed as a
+space that extends to the next tab stop column (normally every 8
+columns). The number of spaces per tab is controlled by the
+buffer-local variable @code{tab-width}, which must have an integer
+value between 1 and 1000, inclusive. Note that how the tab character
+in the buffer is displayed has nothing to do with the definition of
+@key{TAB} as a command.
+
+ Other @acronym{ASCII} control characters, whose codes are below
+@code{U+0020} (octal 40, decimal 32), are displayed as a caret
+(@samp{^}) followed by the non-control version of the character, with
+the @code{escape-glyph} face. For instance, the @samp{control-A}
+character, @code{U+0001}, is displayed as @samp{^A}.
+
+@cindex octal escapes
@vindex ctl-arrow
- If the variable @code{ctl-arrow} is @code{nil}, control characters in
-the buffer are displayed with octal escape sequences, except for newline
-and tab. Altering the value of @code{ctl-arrow} makes it local to the
-current buffer; until that time, the default value is in effect. The
-default is initially @code{t}.
-
- The display of character codes 0240 through 0377 (octal) may be
-either as escape sequences or as graphics. They do not normally occur
-in multibyte buffers, but if they do, they are displayed as Latin-1
-graphics. In unibyte mode, if you enable European display they are
-displayed using their graphics (assuming your terminal supports them),
-otherwise as escape sequences. @xref{Unibyte Mode}.
+ The raw bytes with codes @code{U+0080} (octal 200) through
+@code{U+009F} (octal 237) are displayed as @dfn{octal escape
+sequences}, with the @code{escape-glyph} face. For instance,
+character code @code{U+0098} (octal 230) is displayed as @samp{\230}.
+If you change the buffer-local variable @code{ctl-arrow} to
+@code{nil}, the @acronym{ASCII} control characters are also displayed
+as octal escape sequences instead of caret escape sequences.
@vindex nobreak-char-display
-@cindex no-break space, display
-@cindex no-break hyphen, display
-@cindex soft hyphen, display
- Some character sets define ``no-break'' versions of the space and
-hyphen characters, which are used where a line should not be broken.
-Emacs normally displays these characters with special faces
-(respectively, @code{nobreak-space} and @code{escape-glyph}) to
-distinguish them from ordinary spaces and hyphens. You can turn off
-this feature by setting the variable @code{nobreak-char-display} to
-@code{nil}. If you set the variable to any other value, that means to
-prefix these characters with an escape character.
+@cindex non-breaking space
+@cindex non-breaking hyphen
+@cindex soft hyphen
+ Some non-@acronym{ASCII} characters have the same appearance as an
+@acronym{ASCII} space or hyphen (minus) character. Such characters
+can cause problems if they are entered into a buffer without your
+realization, e.g.@: by yanking; for instance, source code compilers
+typically do not treat non-@acronym{ASCII} spaces as whitespace
+characters. To deal with this problem, Emacs displays such characters
+specially: it displays @code{U+00A0} (no-break space) with the
+@code{nobreak-space} face, and it displays @code{U+00AD} (soft
+hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking
+hyphen) with the @code{escape-glyph} face. To disable this, change
+the variable @code{nobreak-char-display} to @code{nil}. If you give
+this variable a non-@code{nil} and non-@code{t} value, Emacs instead
+displays such characters as a highlighted backslash followed by a
+space or hyphen.
You can customize the way any particular character code is displayed
by means of a display table. @xref{Display Tables,, Display Tables,
@cindex glyphless characters
@cindex characters with no font glyphs
- On graphics displays, some characters could have no glyphs in any of
-the fonts available to Emacs. On text terminals, some characters
-could be impossible to encode with the terminal coding system
-(@pxref{Terminal Coding}). Emacs can display such @dfn{glyphless}
-characters using one of the following methods:
-
-@table @code
-@item zero-width
-Don't display the character.
-
-@item thin-space
-Display a thin space, 1-pixel wide on graphics displays or 1-character
-wide on text terminals.
-
-@item empty-box
-Display an empty box.
-
-@item acronym
-Display the acronym of the character's name (such as @sc{zwnj} or
-@sc{rlm}) in a box.
-
-@item hex-code
-Display the Unicode codepoint of the character in hexadecimal
-notation, in a box.
-@end table
-
-@noindent
-@cindex @code{glyphless-char} face
-With the exception of @code{zero-width}, all other methods draw these
-characters in a special face @code{glyphless-char}, which you can
-customize.
-
-@vindex glyphless-char-display-control
-@vindex char-acronym-table
-To control what glyphless characters are displayed using which method,
-customize the variable @code{glyphless-char-display-control}; see its
-doc string for the details. For even finer control, set the elements
-of 2 char-tables: @code{glyphless-char-display} and
-@code{char-acronym-table}.
+ On graphical displays, some characters may have no glyphs in any of
+the fonts available to Emacs. These @dfn{glyphless characters} are
+normally displayed as boxes containing the hexadecimal character code.
+Similarly, on text terminals, characters that cannot be displayed
+using the terminal encoding (@pxref{Terminal Coding}) are normally
+displayed as question signs. You can control the display method by
+customizing the variable @code{glyphless-char-display-control}.
+@xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs
+Lisp Reference Manual}, for details.
@node Cursor Display
@section Displaying the Cursor
-
-@findex blink-cursor-mode
-@vindex blink-cursor-alist
-@cindex cursor, locating visually
-@cindex cursor, blinking
- You can customize the cursor's color, and whether it blinks, using
-the @code{cursor} Custom group (@pxref{Easy Customization}). On
-a graphical display, the command @kbd{M-x blink-cursor-mode} enables
-or disables the blinking of the cursor. (On text terminals, the
-terminal itself blinks the cursor, and Emacs has no control over it.)
-You can control how the cursor appears when it blinks off by setting
-the variable @code{blink-cursor-alist}.
+@cindex text cursor
@vindex visible-cursor
- Some text terminals offer two different cursors: the normal cursor
-and the very visible cursor, where the latter may be e.g. bigger or
-blinking. By default Emacs uses the very visible cursor, and switches
-to it when you start or resume Emacs. If the variable
-@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it
-doesn't switch, so it uses the normal cursor.
+ On a text terminal, the cursor's appearance is controlled by the
+terminal, largely out of the control of Emacs. Some terminals offer
+two different cursors: a ``visible'' static cursor, and a ``very
+visible'' blinking cursor. By default, Emacs uses the very visible
+cursor, and switches to it when you start or resume Emacs. If the
+variable @code{visible-cursor} is @code{nil} when Emacs starts or
+resumes, it uses the normal cursor.
+
+@cindex cursor face
+@vindex cursor-type
+ On a graphical display, many more properties of the text cursor can
+be altered. To customize its color, change the @code{:background}
+attribute of the face named @code{cursor} (@pxref{Face
+Customization}). (The other attributes of this face have no effect;
+the text shown under the cursor is drawn using the frame's background
+color.) To change its shape, customize the buffer-local variable
+@code{cursor-type}; possible values are @code{box} (the default),
+@code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar
+. @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a
+horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n}
+pixels tall), or @code{nil} (no cursor at all).
-@cindex cursor in non-selected windows
-@vindex cursor-in-non-selected-windows
- Normally, the cursor appears in non-selected windows without
-blinking, with the same appearance as when the blinking cursor blinks
-``off.'' For a box cursor, this is a hollow box; for a bar cursor,
-this is a thinner bar. To turn off cursors in non-selected windows,
-customize the variable @code{cursor-in-non-selected-windows} and
-assign it a @code{nil} value.
+@findex blink-cursor-mode
+@cindex cursor, blinking
+@cindex blinking cursor
+@vindex blink-cursor-alist
+ To disable cursor blinking, change the variable
+@code{blink-cursor-mode} to @code{nil} (@pxref{Easy Customization}),
+or add the line @code{(blink-cursor-mode 0)} to your init file.
+Alternatively, you can change how the cursor looks when it ``blinks
+off'' by customizing the list variable @code{blink-cursor-alist}.
+Each element in the list should have the form @code{(@var{on-type}
+. @var{off-type})}; this means that if the cursor is displayed as
+@var{on-type} when it blinks on (where @var{on-type} is one of the
+cursor types described above), then it is displayed as @var{off-type}
+when it blinks off.
@vindex x-stretch-cursor
@cindex wide block cursor
- On graphical displays, Emacs can optionally draw the block cursor
-as wide as the character under the cursor---for example, if the cursor
-is on a tab character, it would cover the full width occupied by that
-tab character. To enable this feature, set the variable
+ Some characters, such as tab characters, are ``extra wide''. When
+the cursor is positioned over such a character, it is normally drawn
+with the default character width. You can make the cursor stretch to
+cover wide characters, by changing the variable
@code{x-stretch-cursor} to a non-@code{nil} value.
+@cindex cursor in non-selected windows
+@vindex cursor-in-non-selected-windows
+ The cursor normally appears in non-selected windows as a
+non-blinking hollow box. (For a bar cursor, it instead appears as a
+thinner bar.) To turn off cursors in non-selected windows, change the
+variable @code{cursor-in-non-selected-windows} to @code{nil}.
+
@findex hl-line-mode
@findex global-hl-line-mode
@cindex highlight current line
global-hl-line-mode} enables or disables the same mode globally.
@node Line Truncation
-@section Truncation of Lines
+@section Line Truncation
@cindex truncation
@cindex line truncation, and fringes
- As an alternative to continuation (@pxref{Continuation Lines}), Emacs
-can display long lines by @dfn{truncation}. This means that all the
-characters that do not fit in the width of the screen or window do not
-appear at all. On graphical displays, a small straight arrow in the
-fringe indicates truncation at either end of the line. On text-only
-terminals, @samp{$} appears in the leftmost column when there is text
-truncated to the left, and in the rightmost column when there is text
-truncated to the right.
+ As an alternative to continuation (@pxref{Continuation Lines}),
+Emacs can display long lines by @dfn{truncation}. This means that all
+the characters that do not fit in the width of the screen or window do
+not appear at all. On graphical displays, a small straight arrow in
+the fringe indicates truncation at either end of the line. On text
+terminals, this is indicated with @samp{$} signs in the leftmost
+and/or rightmost columns.
@vindex truncate-lines
@findex toggle-truncate-lines
are truncated; if it is @code{nil}, they are continued onto multiple
screen lines. Setting the variable @code{truncate-lines} in any way
makes it local to the current buffer; until that time, the default
-value is in effect. The default value is normally @code{nil}.
+value, which is normally @code{nil}, is in effect.
-@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
- If the variable @code{truncate-partial-width-windows} is
-non-@code{nil}, it forces truncation rather than continuation in any
-window less than the full width of the screen or frame, regardless of
-the value of @code{truncate-lines}. See also @ref{Display,, Display,
-elisp, The Emacs Lisp Reference Manual}.
-
-@vindex overflow-newline-into-fringe
- If the variable @code{overflow-newline-into-fringe} is
-non-@code{nil} on a graphical display, then Emacs does not continue or
-truncate a line which is exactly as wide as the window. Instead, the
-newline overflows into the right fringe, and the cursor appears in the
-fringe when positioned on that newline.
+@vindex truncate-partial-width-windows
+ If a split window becomes too narrow, Emacs may automatically enable
+line truncation. @xref{Split Window}, for the variable
+@code{truncate-partial-width-windows} which controls this.
@node Visual Line Mode
@section Visual Line Mode
@node Display Custom
@section Customization of Display
- This section describes variables (@pxref{Variables}) that you can
-change to customize how Emacs displays. Beginning users can skip
-it.
-@c the reason for that pxref is because an xref early in the
-@c ``echo area'' section leads here.
+ This section describes variables that control miscellaneous aspects
+of the appearance of the Emacs screen. Beginning users can skip it.
@vindex visible-bell
If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
The variable @code{echo-keystrokes} controls the echoing of multi-character
keys; its value is the number of seconds of pause required to cause echoing
to start, or zero, meaning don't echo at all. The value takes effect when
-there is someting to echo. @xref{Echo Area}.
-
-@vindex baud-rate
- The variable @anchor{baud-rate}@code{baud-rate} holds the output
-speed of the terminal. Setting this variable does not change the
-speed of actual data transmission, but the value is used for
-calculations. On text-only terminals, it affects padding, and
-decisions about whether to scroll part of the screen or redraw it
-instead. It also affects the behavior of incremental search. On
-graphical displays, @code{baud-rate} is only used to determine how
-frequently to look for pending input during display updating. A
-higher value of @code{baud-rate} means that check for pending input
-will be done less frequently.
+there is something to echo. @xref{Echo Area}.
@cindex mouse pointer
@cindex hourglass pointer display
itself, in pixels; the default is 2.
@findex tty-suppress-bold-inverse-default-colors
- On some text-only terminals, bold face and inverse video together
-result in text that is hard to read. Call the function
+ On some text terminals, bold face and inverse video together result
+in text that is hard to read. Call the function
@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
argument to suppress the effect of bold-face in this case.
-
-@vindex no-redraw-on-reenter
- On a text-only terminal, when you reenter Emacs after suspending, Emacs
-normally clears the screen and redraws the entire display. On some
-terminals with more than one page of memory, it is possible to arrange
-the termcap entry so that the @samp{ti} and @samp{te} strings (output
-to the terminal when Emacs is entered and exited, respectively) switch
-between pages of memory so as to use one page for Emacs and another
-page for other output. On such terminals, you might want to set the variable
-@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to
-assume, when resumed, that the screen page it is using still contains
-what Emacs last wrote there.
HCoop / bpt / emacs.git / blobdiff