* help-fns.el (describe-variable): Add info about safe local variables.

[bpt/emacs.git] / man / screen.texi

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
@c   2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Screen, User Input, Acknowledgments, Top
@chapter The Organization of the Screen
@cindex screen
@cindex parts of the screen

  On a text-only terminal, the Emacs display occupies the whole
screen.  On a graphical display, such as on GNU/Linux using the X
Window System, Emacs creates its own windows to use.  We use the term
@dfn{frame} to mean the entire text-only screen or an entire
system-level window used by Emacs.  Emacs uses both kinds of frames,
in the same way, to display your editing.  Emacs normally starts out
with just one frame, but you can create additional frames if you wish.
@xref{Frames}.

  When you start Emacs, the main central area of the frame, all except
for the top and bottom and sides, displays the text you are editing.
This area is called @dfn{the window}.  At the top there is normally a
@dfn{menu bar} where you can access a series of menus; then there may
be a @dfn{tool bar}, a row of icons that perform editing commands if
you click on them.  Below this, the window begins, often with a
@dfn{scroll bar} on one side.  Below the window comes the last line of
the frame, a special @dfn{echo area} or @dfn{minibuffer window}, where
prompts appear and where you enter information when Emacs asks for it.
See following sections for more information about these special lines.

  You can subdivide the window horizontally or vertically to make
multiple text windows, each of which can independently display some
file or text (@pxref{Windows}).  In this manual, the word ``window''
refers to the initial large window if not subdivided, or any one of
the multiple windows you have subdivided it into.

  At any time, one window is the @dfn{selected window}.  On graphical
terminals, the selected window normally shows a more prominent cursor
(usually solid and blinking) while other windows show a weaker cursor
(such as a hollow box).  On text terminals, which have just one
cursor, that cursor always appears in the selected window.

  Most Emacs commands implicitly apply to the text in the selected
window (though mouse commands generally operate on whatever window you
click them in, whether selected or not).  The text in other windows is
mostly visible for reference, unless/until you select them.  If you
use multiple frames on a graphical display, then giving the input
focus to a particular frame selects a window in that frame.

  Each window's last line is a @dfn{mode line}, which describes what
is going on in that window.  It appears in different color and/or a
``3D'' box, if the terminal supports that; its contents normally begin
with @w{@samp{--:-- @ *scratch*}} when Emacs starts.  The mode line
displays status information such as what buffer is being displayed
above it in the window, what major and minor modes are in use, and
whether the buffer contains unsaved changes.

@menu
* Point::	        The place in the text where editing commands operate.
* Echo Area::           Short messages appear at the bottom of the screen.
* Mode Line::	        Interpreting the mode line.
* Menu Bar::            How to use the menu bar.
@end menu

@node Point
@section Point
@cindex point
@cindex cursor

  Within Emacs, the active cursor shows the location at which
editing commands will take effect.  This location is called @dfn{point}.
Many Emacs commands move point through the text, so that you can edit at
different places in it.  You can also place point by clicking mouse
button 1 (normally the left button).

  While the cursor appears to be @emph{on} a character, you should
think of point as @emph{between} two characters; it points @emph{before}
the character that appears under the cursor.  For example, if your text
looks like @samp{frob} with the cursor over the @samp{b}, then point is
between the @samp{o} and the @samp{b}.  If you insert the character
@samp{!} at that position, the result is @samp{fro!b}, with point
between the @samp{!} and the @samp{b}.  Thus, the cursor remains over
the @samp{b}, as before.

  Sometimes people speak of ``the cursor'' when they mean ``point,'' or
speak of commands that move point as ``cursor motion'' commands.

  If you are editing several files in Emacs, each in its own buffer,
each buffer has its own point location.  A buffer that is not
currently displayed remembers its point location in case you display
it again later.  When Emacs displays multiple windows, each window has
its own point location.  If the same buffer appears in more than one
window, each window has its own position for point in that buffer, and
(when possible) its own cursor.

  A text-only terminal has just one cursor, so Emacs puts it
in the selected window.  The other windows do not show a cursor, even
though they do have a location of point.  When Emacs updates the
screen on a text-only terminal, it has to put the cursor temporarily
at the place the output goes.  This doesn't mean point is there,
though.  Once display updating finishes, Emacs puts the cursor where
point is.

  On graphical terminals, Emacs shows a cursor in each window; the
selected window's cursor is solid and blinking, and the other cursors
are just hollow.  Thus, the most prominent cursor always shows you the
selected window, on all kinds of terminals.

  @xref{Cursor Display}, for customizable variables that control display
of the cursor or cursors.

  The term ``point'' comes from the character @samp{.}, which was the
command in TECO (the language in which the original Emacs was written)
for accessing the value now called ``point.''

@node Echo Area
@section The Echo Area
@cindex echo area

  The line at the bottom of the frame (below the mode line) is the
@dfn{echo area}.  It is used to display small amounts of text for
various purposes.

  @dfn{Echoing} means displaying the characters that you type.  At the
command line, the operating system normally echoes all your input.
Emacs handles echoing differently.

  Single-character commands do not echo in Emacs, and multi-character
commands echo only if you pause while typing them.  As soon as you pause
for more than a second in the middle of a command, Emacs echoes all the
characters of the command so far.  This is to @dfn{prompt} you for the
rest of the command.  Once echoing has started, the rest of the command
echoes immediately as you type it.  This behavior is designed to give
confident users fast response, while giving hesitant users maximum
feedback.  You can change this behavior by setting a variable
(@pxref{Display Custom}).

@cindex error message in the echo area
  If a command cannot do its job, it may display an @dfn{error
message} in the echo area.  Error messages are accompanied by beeping
or by flashing the screen.  The error also discards any input you have
typed ahead.

  Some commands display informative messages in the echo area.  These
messages look much like error messages, but they are not announced
with a beep and do not throw away input.  Sometimes the message tells
you what the command has done, when this is not obvious from looking
at the text being edited.  Sometimes the sole purpose of a command is
to show you a message giving you specific information---for example,
@kbd{C-x =} (hold down @key{CTRL} and type @kbd{x}, then let go of
@key{CTRL} and type @kbd{=}) displays a message describing the
character position of point in the text and its current column in the
window.  Commands that take a long time often display messages ending
in @samp{...} while they are working, and add @samp{done} at the end
when they are finished.  They may also indicate progress with
percentages.

@cindex @samp{*Messages*} buffer
@cindex saved echo area messages
@cindex messages saved from echo area
  Echo-area informative messages are saved in an editor buffer named
@samp{*Messages*}.  (We have not explained buffers yet; see
@ref{Buffers}, for more information about them.)  If you miss a message
that appears briefly on the screen, you can switch to the
@samp{*Messages*} buffer to see it again.  (Successive progress messages
are often collapsed into one in that buffer.)

@vindex message-log-max
  The size of @samp{*Messages*} is limited to a certain number of lines.
The variable @code{message-log-max} specifies how many lines.  Once the
buffer has that many lines, each line added at the end deletes one line
from the beginning.  @xref{Variables}, for how to set variables such as
@code{message-log-max}.

  The echo area is also used to display the @dfn{minibuffer}, a window that
is used for reading arguments to commands, such as the name of a file to be
edited.  When the minibuffer is in use, the echo area begins with a prompt
string that usually ends with a colon; also, the cursor appears in that line
because it is the selected window.  You can always get out of the
minibuffer by typing @kbd{C-g}.  @xref{Minibuffer}.

@node Mode Line
@section The Mode Line
@cindex mode line
@cindex top level
@c

  Each text window's last line is a @dfn{mode line}, which describes
what is going on in that window.  The mode line starts and ends with
dashes.  When there is only one text window, the mode line appears
right above the echo area; it is the next-to-last line in the frame.
On a text-mode display, the mode line is in inverse video if the
terminal supports that; on a graphics display, the mode line has a 3D
box appearance to help it stand out.  The mode line of the selected
window has a slightly different appearance than those of other
windows; see @ref{Optional Mode Line}, for more about this.

  Normally, the mode line looks like this:

@example
-@var{cs}:@var{ch}-@var{fr}  @var{buf}      @var{pos} @var{line}   (@var{major} @var{minor})------
@end example

@noindent
This gives information about the buffer being displayed in the window: the
buffer's name, what major and minor modes are in use, whether the buffer's
text has been changed, and how far down the buffer you are currently
looking.

  @var{ch} contains two stars @samp{**} if the text in the buffer has
been edited (the buffer is ``modified''), or @samp{--} if the buffer has
not been edited.  For a read-only buffer, it is @samp{%*} if the buffer
is modified, and @samp{%%} otherwise.

  @var{fr} appears only on text-only terminals, to show the selected
frame name.  @xref{Frames}.  The initial frame's name is @samp{F1}.

  @var{buf} is the name of the window's @dfn{buffer}.  In most cases
this is the same as the name of a file you are editing.  @xref{Buffers}.

  The buffer displayed in the selected window (the window that the
cursor is in) is the @dfn{current buffer}--the one that editing takes
place in.  When we speak of what some command does to ``the buffer,''
we mean it does those things to the current buffer.

  @var{pos} tells you whether there is additional text above the top of
the window, or below the bottom.  If your buffer is small and it is all
visible in the window, @var{pos} is @samp{All}.  Otherwise, it is
@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot}
if you are looking at the end of the buffer, or @samp{@var{nn}%}, where
@var{nn} is the percentage of the buffer above the top of the window.
With Size Indication mode, you can display the size of the buffer as
well.  @xref{Optional Mode Line}.

  @var{line} is @samp{L} followed by the current line number of point.
This is present when Line Number mode is enabled (which it normally is).
You can optionally display the current column number too, by turning on
Column Number mode (which is not enabled by default because it is
somewhat slower).  @xref{Optional Mode Line}.

  @var{major} is the name of the @dfn{major mode} in effect in the
buffer.  At any time, each buffer is in one and only one of the possible
major modes.  The major modes available include Fundamental mode (the
least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many
others.  @xref{Major Modes}, for details of how the modes differ and how
to select one.@refill

  Some major modes display additional information after the major mode
name.  For example, Rmail buffers display the current message number and
the total number of messages.  Compilation buffers and Shell buffers
display the status of the subprocess.

  @var{minor} is a list of some of the @dfn{minor modes} that are
turned on at the moment in the window's chosen buffer.  For example,
@samp{Fill} means that Auto Fill mode is on.  @samp{Abbrev} means that
Word Abbrev mode is on.  @samp{Ovwrt} means that Overwrite mode is on.
@xref{Minor Modes}, for more information.  @samp{Narrow} means that
the buffer being displayed has editing restricted to only a portion of
its text.  (This is not really a minor mode, but is like one.)
@xref{Narrowing}.  @samp{Def} means that a keyboard macro is being
defined.  @xref{Keyboard Macros}.

  In addition, if Emacs is currently inside a recursive editing level,
square brackets (@samp{[@dots{}]}) appear around the parentheses that
surround the modes.  If Emacs is in one recursive editing level within
another, double square brackets appear, and so on.  Since recursive
editing levels affect Emacs globally, not just one buffer, the square
brackets appear in every window's mode line or not in any of them.
@xref{Recursive Edit}.@refill

  @var{cs} states the coding system used for the file you are editing.
A dash indicates the default state of affairs: no code conversion,
except for end-of-line translation if the file contents call for that.
@samp{=} means no conversion whatsoever.  Nontrivial code conversions
are represented by various letters---for example, @samp{1} refers to ISO
Latin-1.  @xref{Coding Systems}, for more information.

  On a text-only terminal, @var{cs} includes two additional characters
which describe the coding system for keyboard input and the coding
system for terminal output.  They come right before the coding system
used for the file you are editing.

  If you are using an input method, a string of the form
@samp{@var{i}>} is added to the beginning of @var{cs}; @var{i}
identifies the input method.  (Some input methods show @samp{+} or
@samp{@@} instead of @samp{>}.)  @xref{Input Methods}.

  When multibyte characters are not enabled, @var{cs} does not appear at
all.  @xref{Enabling Multibyte}.

@cindex end-of-line conversion, mode-line indication
  The colon after @var{cs} can change to another string in certain
circumstances.  Emacs uses newline characters to separate lines in the buffer.
Some files use different conventions for separating lines: either
carriage-return linefeed (the MS-DOS convention) or just carriage-return
(the Macintosh convention).  If the buffer's file uses carriage-return
linefeed, the colon changes to either a backslash (@samp{\}) or
@samp{(DOS)}, depending on the operating system.  If the file uses just
carriage-return, the colon indicator changes to either a forward slash
(@samp{/}) or @samp{(Mac)}.  On some systems, Emacs displays
@samp{(Unix)} instead of the colon even for files that use newline to
separate lines.

  @xref{Optional Mode Line}, for features that add other handy
information to the mode line, such as the size of the buffer, the
current column number of point, and whether new mail for you has
arrived.

  The mode line is mouse-sensitive; when you move the mouse across
various parts of it, Emacs displays help text to say what a click in
that place will do.  @xref{Mode Line Mouse}.

@node Menu Bar
@section The Menu Bar
@cindex menu bar

  Each Emacs frame normally has a @dfn{menu bar} at the top which you
can use to perform certain common operations.  There's no need to list
them here, as you can more easily see for yourself.

@kindex M-`
@kindex F10
@findex tmm-menubar
  On a graphical terminal, you can use the mouse to choose a command
from the menu bar.  An arrow pointing right, after the menu item,
indicates that the item leads to a subsidiary menu; @samp{...} at the
end means that the command will read arguments (further input from
you) before it actually does anything.

  To view the full command name and documentation for a menu item, type
@kbd{C-h k}, and then select the menu bar with the mouse in the usual
way (@pxref{Key Help}).

  On text-only terminals with no mouse, you can use the menu bar by
typing @kbd{M-`} or @key{F10} (these run the command
@code{tmm-menubar}).  This command enters a mode in which you can select
a menu item from the keyboard.  A provisional choice appears in the echo
area.  You can use the up and down arrow keys to move through the
menu to different choices.  When you have found the choice you want,
type @key{RET} to select it.

  Each menu item also has an assigned letter or digit which designates
that item; it is usually the initial of some word in the item's name.
This letter or digit is separated from the item name by @samp{=>}.  You
can type the item's letter or digit to select the item.

  Some of the commands in the menu bar have ordinary key bindings as
well; if so, the menu lists one equivalent key binding in parentheses
after the item itself.

@ignore
   arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f
@end ignore