@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000, 2001
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000, 2001, 2002
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Display, Search, Registers, Top
* Font Lock:: Minor mode for syntactic highlighting using faces.
* Highlight Changes:: Using colors to show where you changed the buffer.
* Highlight Interactively:: Tell Emacs what text to highlight.
-* Trailing Whitespace:: Showing possibly-spurious trailing whitespace.
* Scrolling:: Moving text up and down in a window.
* Horizontal Scrolling:: Moving text left and right in a window.
+* Fringes:: Enabling or disabling window fringes.
+* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
* Follow Mode:: Follow mode lets two windows scroll as one.
* Selective Display:: Hiding lines with lots of indentation.
* Optional Mode Line:: Optional mode line display features.
@section Using Multiple Typefaces
@cindex faces
- When using Emacs with a window system, you can set up multiple
-styles of displaying characters. Each style is called a @dfn{face}.
-Each face can specify various attributes, such as the height, weight
-and slant of the characters, the foreground and background color, and
-underlining. But it does not have to specify all of them.
+ Emacs supports using multiple styles of displaying characters. Each
+style is called a @dfn{face}. Each face can specify various @dfn{face
+attributes}, such as the font family, the height, weight and slant of
+the characters, the foreground and background color, and underlining
+or overlining. A face does not have to specify all of these
+attributes; often it inherits many of them from another face.
+
+ On a window system, all the Emacs face attributes are meaningful.
+On a character terminal, only some of them work. Some character
+terminals support inverse video, bold, and underline attributes; some
+support colors. Character terminals generally do not support changing
+the height and width or the font family.
Features which rely on text in multiple faces (such as Font Lock mode)
will also work on non-windowed terminals that can display more than one
specifying the face or faces to use for it. The style of display used
for any given character is determined by combining the attributes of
all the applicable faces specified for that character. Any attribute
-that isn't specified by these faces is taken from the default face,
+that isn't specified by these faces is taken from the @code{default} face,
whose attributes reflect the default settings of the frame itself.
Enriched mode, the mode for editing formatted text, includes several
@findex set-face-background
To alter the appearance of a face, use the customization buffer.
@xref{Face Customization}. You can also use X resources to specify
-attributes of particular faces (@pxref{Resources X}). Alternatively,
+attributes of particular faces (@pxref{Resources}). Alternatively,
you can 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.
+color. Changing the colors of the @code{default} face also changes
+the foreground and background colors on all frames, both existing and
+those to be created in the future. (You can also set foreground and
+background colors for the current frame only; see @ref{Frame
+Parameters}.)
Emacs 21 can correctly display variable-width fonts, but Emacs
commands that calculate width and indentation do not know how to
@item default
This face is used for ordinary text that doesn't specify any other face.
@item mode-line
-This face is used for mode lines. By default, it's drawn with shadows
-for a ``raised'' effect on window systems, and drawn as the inverse of
-the default face on non-windowed terminals. @xref{Display Custom}.
+This face is used for the mode line of the currently selected window.
+By default, it's drawn with shadows for a ``raised'' effect on window
+systems, and drawn as the inverse of the default face on non-windowed
+terminals. @xref{Display Custom}.
+@item mode-line-inactive
+Like @code{mode-line}, but used for mode lines of the windows other
+than the selected one (if @code{mode-line-in-non-selected-windows} is
+non-@code{nil}). This face inherits from @code{mode-line}, so changes
+in that face affect mode lines in all windows.
@item header-line
Similar to @code{mode-line} for a window's header line. Most modes
don't use the header line, but the Info mode does.
+@item minibuffer-prompt
+This face is used for the prompt strings displayed in the minibuffer.
@item highlight
This face is used for highlighting portions of text, in various modes.
For example, mouse-sensitive text is highlighted using this face.
the font are ignored in this case.
@item trailing-whitespace
The face for highlighting trailing whitespace when
-@code{show-trailing-whitespace} is non-nil.
+@code{show-trailing-whitespace} is non-@code{nil}; see @ref{Useless
+Whitespace}.
@item variable-pitch
The basic variable-pitch face.
@end table
@cindex mode, Font Lock
@cindex syntax highlighting and coloring
- Font Lock mode is a minor mode, always local to a particular
-buffer, which highlights (or ``fontifies'') using various faces
-according to the syntax of the text you are editing. It can
-recognize comments and strings in most languages; in several
-languages, it can also recognize and properly highlight various other
-important constructs---for example, names of functions being defined
-or reserved keywords.
+ Font Lock mode is a minor mode, always local to a particular buffer,
+which highlights (or ``fontifies'') using various faces according to
+the syntax of the text you are editing. It can recognize comments and
+strings in most languages; in several languages, it can also recognize
+and properly highlight various other important constructs---for
+example, 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.
@findex font-lock-mode
@findex turn-on-font-lock
@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
+@cindex brace in column zero and fontification
Comment and string fontification (or ``syntactic'' fontification)
relies on analysis of the syntactic structure of the buffer text. For
-the purposes of speed, some modes, including C mode and Lisp mode,
+the sake of speed, some modes, including C mode and 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
'(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
@end example
+@findex font-lock-remove-keywords
+ 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}, for
+documentation of the format of this list.
+
+@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. The
+parts of the buffer that are not displayed are fontified
+``stealthily'', in the background, i.e.@: when Emacs is idle. You can
+control this background fontification, called @dfn{Just-In-Time}, or
+@dfn{JIT} Font Lock, by customizing various options in the
+customization group @samp{jit-lock}. @xref{Specific Customization}.
+
@node Highlight Changes
@section Highlight Changes Mode
@code{hi-lock-exclude-modes}.
@end table
-@node Trailing Whitespace
-@section Trailing Whitespace
-
-@cindex trailing whitespace
-@cindex whitespace, trailing
-@vindex show-trailing-whitespace
- It is easy to leave unnecessary spaces at the end of a line without
-realizing it. In most cases, this @dfn{trailing whitespace} has no
-effect, but there are special circumstances where it matters.
-
- You can make trailing whitespace visible on the screen by setting
-the variable @code{show-trailing-whitespace} to @code{t}. Then Emacs
-displays trailing whitespace in the face @code{trailing-whitespace}.
-
- Trailing whitespace is defined as spaces or tabs at the end of a
-line. But trailing whitespace is not displayed specially if point is
-at the end of the line containing the whitespace. (Doing that looks
-ugly while you are typing in new text, and the location of point is
-enough in that case to show you that the spaces are present.)
-
-@vindex indicate-empty-lines
-@vindex default-indicate-empty-lines
-@cindex empty lines
- Emacs can indicate empty lines at the end of the buffer with a
-special bitmap on the left fringe of the window. To enable this
-feature, set the buffer-local variable @code{indicate-empty-lines} to
-a non-@code{nil} value. The default value of this variable is
-controlled by the variable @code{default-indicate-empty-lines};
-by setting that variable, you can enable or disable this feature
-for all new buffers.
-
@node Scrolling
@section Scrolling
was in the text that scrolled off the top, it ends up at the new top
of the window.
- @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward
-similarly with overlap. The number of lines of overlap across a
-@kbd{C-v} or @kbd{M-v} is controlled by the variable
+ @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in
+a similar way, also with overlap. The number of lines of overlap
+across a @kbd{C-v} or @kbd{M-v} is controlled by the variable
@code{next-screen-context-lines}; 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}.
@cindex aggressive scrolling
@vindex scroll-up-aggressively
-@vindex scroll-down-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}.
to scroll the window, but never farther to the right than the amount
you previously set by @code{scroll-left}.
-@vindex automatic-hscrolling
+@vindex hscroll-margin
+ The value of the variable @code{hscroll-margin} controls how close
+to the window's edges point is allowed to get before the window will
+be automatically scrolled. It is measured in columns. If the value
+is 5, then moving point within 5 columns of the edge causes horizontal
+scrolling away from that edge.
+
+@vindex hscroll-step
+ The variable @code{hscroll-step} determines how many columns to
+scroll the window when point gets too close to the edge. If it's
+zero, horizontal scrolling centers point horizontally within the
+window. If it's a positive integer, it specifies the number of
+columns to scroll by. If it's a floating-point number, it specifies
+the fraction of the window's width to scroll by. The default is zero.
+
+@vindex auto-hscroll-mode
To disable automatic horizontal scrolling, set the variable
-@code{automatic-hscrolling} to @code{nil}.
+@code{auto-hscroll-mode} to @code{nil}.
+
+@node Fringes
+@section Window Fringes
+@cindex fringes
+
+ On a graphical display, each Emacs window normally has narrow
+@dfn{fringes} on the left and right edges. The fringes display
+indications about the text in the window.
+
+ 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.''
+
+ 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 also indicate other things such as empty lines, or where a
+program you are debugging is executing (@pxref{Debuggers}).
+
+@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}.
+
+@node Useless Whitespace
+@section Useless Whitespace
+
+@cindex trailing whitespace
+@cindex whitespace, trailing
+@vindex show-trailing-whitespace
+ It is easy to leave unnecessary spaces at the end of a line, or
+empty lines at the end of a file, without realizing it. In most
+cases, this @dfn{trailing whitespace} has no effect, but there are
+special circumstances where it matters.
+
+ You can make trailing whitespace at the end of a line visible on the
+screen by setting the buffer-local variable
+@code{show-trailing-whitespace} to @code{t}. Then Emacs displays
+trailing whitespace in the face @code{trailing-whitespace}.
+
+ This feature does not apply when point is at the end of the line
+containing the whitespace. Strictly speaking, that is ``trailing
+whitespace'' nonetheless, but displaying it specially in that case
+looks ugly while you are typing in new text. In this special case,
+the location of point is enough to show you that the spaces are
+present.
+
+@findex delete-trailing-whitespace
+ To delete all trailing whitespace within the current buffer's
+accessible portion (@pxref{Narrowing}), type @kbd{M-x
+delete-trailing-whitespace @key{RET}}. (This command does not remove
+the form-feed characters.)
+
+@vindex indicate-unused-lines
+@vindex default-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-unused-lines} to a non-@code{nil} value. The default
+value of this variable is controlled by the variable
+@code{default-indicate-unused-lines}; by setting that variable, you
+can enable or disable this feature for all new buffers. (This feature
+currently doesn't work on character terminals.)
@node Follow Mode
@section Follow Mode
@node Optional Mode Line
@section Optional Mode Line Features
+@cindex buffer size display
+@cindex display of buffer size
+@findex size-indication-mode
+ The buffer percentage @var{pos} indicates the percentage of the
+buffer above the top of the window. You can additionally display the
+size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
+Size Indication mode. The size will be displayed immediately
+following the buffer percentage like this:
+
+@example
+@var{POS} of @var{SIZE}
+@end example
+
+@noindent
+Here @var{SIZE} is the human readable representation of the number of
+characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
+for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
+
+@cindex narrowing, and buffer size display
+ If you have narrowed the buffer (@pxref{Narrowing}), the size of the
+accessible part of the buffer is shown.
+
@cindex line number display
@cindex display of line number
@findex line-number-mode
The current line number of point appears in the mode line when Line
Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
turn this mode on and off; normally it is on. The line number appears
-before the buffer percentage @var{pos}, with the letter @samp{L} to
+after the buffer percentage @var{pos}, with the letter @samp{L} to
indicate what it is. @xref{Minor Modes}, for more information about
minor modes and about how to use this command.
@cindex mail (on mode line)
@vindex display-time-use-mail-icon
@vindex display-time-mail-face
+@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.
+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 mode line, 3D appearence
+@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
Emacs.mode-line.AttributeBox: off
@end example
+@cindex non-selected windows, mode line appearance
+ By default, the mode line of nonselected windows is displayed in a
+different face, called @code{mode-line-inactive}. Only the selected
+window is displayed in the @code{mode-line} face. This helps show
+which window is selected. When the minibuffer is selected, since
+it has no mode line, the window from which you activated the minibuffer
+has its mode line displayed using @code{mode-line}; as a result,
+ordinary entry to the minibuffer does not change any mode lines.
+
+@vindex mode-line-in-non-selected-windows
+ You can disable use of @code{mode-line-inactive} by setting variable
+@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
+lines are displayed in the @code{mode-line} face.
+
@node Text Display
@section How Text Is Displayed
@cindex characters (in text)
- ASCII printing characters (octal codes 040 through 0176) in Emacs
+ @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs
buffers are displayed with their graphics, as are non-ASCII multibyte
printing characters (octal codes above 0400).
- Some ASCII control characters are displayed in special ways. The
+ 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).
- Other ASCII control characters are normally displayed as a caret
+ 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}.
- Non-ASCII characters 0200 through 0237 (octal) are displayed with
+ 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 display of character codes 0240 through 0377
(octal) may be either as escape sequences or as graphics. They do not
The variable @code{mode-line-inverse-video} is an obsolete way of
controlling whether the mode line is displayed in inverse video; the
preferred way of doing this is to change the @code{mode-line} face.
-@xref{Mode Line}. If you specify the foreground color for the
-@code{mode-line} face, and @code{mode-line-inverse-video} is
-non-@code{nil}, then the default background color for that face is the
-usual foreground color. @xref{Faces}.
+@xref{Mode Line}. However, if @code{mode-line-inverse-video} has a
+value of @code{nil}, then the @code{mode-line} face will be ignored,
+and mode-lines will be drawn using the default text face.
+@xref{Faces}.
@vindex inverse-video
If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
windows, see @ref{Split Window}. 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 window system, it specifies that lines which are
+exactly as wide as the window (not counting the final newline
+character) shall not be broken into two lines on the display (with
+just the newline on the second line). Instead, the newline
+overflows into the right fringe, and the cursor will be displayed in
+the fringe when positioned on that newline.
+
+@vindex indicate-buffer-boundaries
+ On a window system, Emacs may indicate the buffer boundaries in the
+fringes. The buffer boundaries, i.e. first and last line in the
+buffer, can be marked with angle bitmaps in the left or right fringe.
+This can be combined with up and down arrow bitmaps shown at the top
+and bottom of the left or right fringe if the window can be scrolled
+in either direction.
+
+ The buffer-local variable @code{indicate-buffer-boundaries} controls
+how the buffer boundaries and window scrolling is indicated in the
+fringes.
+
+ If the value is @code{left} or @code{right}, both angle and arrow
+bitmaps are displayed in the left or right fringe, respectively.
+
+ If value is an alist, each element @code{(@var{indicator} .
+@var{position})} specifies the position of one of the indicators.
+The @var{indicator} must be one of @code{top}, @code{bottom},
+@code{up}, @code{down}, or @code{t} which specifies the default
+position for the indicators not present in the alist.
+The @var{position} is one of @code{left}, @code{right}, or @code{ni}
+which specifies not to show this indicator.
+
+ For example, @code{((top . left) (t . right))} places the top angle
+bitmap in left fringe, the bottom angle bitmap in right fringe, and
+both arrow bitmaps in right fringe. To show just the angle bitmaps in
+the left fringe, but no arrow bitmaps, use @code{((top . left)
+(bottom . left))}.
+
+@vindex default-indicate-buffer-boundaries
+ The value of the variable @code{default-indicate-buffer-boundaries}
+is the default value for @code{indicate-buffer-boundaries} in buffers
+that do not override it.
+
@vindex baud-rate
The variable @code{baud-rate} holds the output speed of the
terminal, as far as Emacs knows. Setting this variable does not
amount of time Emacs must remain busy before the busy indicator is
displayed, by setting the variable @code{hourglass-delay}.
+@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
+@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
+argument to suppress the effect of bold-face in this case.
+
@node Cursor Display
@section Displaying the Cursor
-@findex hl-line-mode
@findex blink-cursor-mode
+@vindex blink-cursor-alist
@cindex cursor, locating visually
@cindex cursor, blinking
- There are a number of ways to customize the display of the cursor.
-@kbd{M-x hl-line-mode} enables or disables a global minor mode which
-highlights the line containing point. On window systems, the command
-@kbd{M-x blink-cursor-mode} turns on or off the blinking of the
-cursor. (On terminals, the terminal itself blinks the cursor, and
-Emacs has no control over it.)
-
You can customize the cursor's color, and whether it blinks, using
-the @code{cursor} Custom group (@pxref{Easy Customization}).
+the @code{cursor} Custom group (@pxref{Easy Customization}). On
+graphical terminals, 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 cursor in non-selected windows
+@vindex cursor-in-non-selected-windows
+ Normally, the cursor appears in non-selected windows in the ``off''
+state, 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 option @code{cursor-in-non-selected-windows} and assign
+it a @code{nil} value.
@vindex x-stretch-cursor
@cindex wide block cursor
- When displaying on a window system, 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 @code{x-stretch-cursor} to a non-@code{nil} value.
+ On graphical terminals, 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
+@code{x-stretch-cursor} to a non-@code{nil} value.
-@cindex cursor in non-selected windows
-@vindex cursor-in-non-selected-windows
- Normally, the cursor in non-selected windows is shown as a hollow box.
-To turn off cursor display in non-selected windows, customize the option
-@code{cursor-in-non-selected-windows} to assign it a @code{nil} value.
+@findex hl-line-mode
+@findex global-hl-line-mode
+@cindex highlight current line
+ If you find it hard to see the cursor, you might like HL Line mode,
+a minor mode that highlights the line containing point. Use @kbd{M-x
+hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x
+global-hl-line-mode} enables or disables the same mode globally.
+
+@ignore
+ arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4
+@end ignore
HCoop / bpt / emacs.git / blobdiff