code:
@node Text, Programs, Indentation, Top
@chapter Commands for Human Languages
@cindex text

  The term @dfn{text} has two widespread meanings in our area of the
computer field.  One is data that is a sequence of characters.  In this
sense of the word any file that you edit with Emacs is text.  The other
meaning is more restrictive: a sequence of characters in a human
language for humans to read (possibly after processing by a text
formatter), as opposed to a program or commands for a program.

  Human languages have syntactic and stylistic conventions that editor
commands should support or use to advantage: conventions involving
words, sentences, paragraphs, and capital letters.  This chapter describes
Emacs commands for all these things.  There are also commands for
@dfn{filling}, or rearranging paragraphs into lines of approximately equal
length.  The commands for moving over and killing words, sentences,
and paragraphs, while intended primarily for editing text, are also often
useful for editing programs.

  Emacs has several major modes for editing human language text.
If a file contains plain text, use Text mode, which customizes
Emacs in small ways for the syntactic conventions of text.  For text which
contains embedded commands for text formatters, Emacs has other major modes,
each for a particular text formatter.  Thus, for input to @TeX{}, you can
use @TeX{} mode; for input to nroff, Nroff mode.

@menu
* Text Mode::   The major modes for editing text files.
* Nroff Mode::  The major mode for editing input to the formatter nroff.
* TeX Mode::    The major modes for editing input to the formatter TeX.
* Outline Mode:: The major mode for editing outlines.
* Words::       Moving over and killing words.
* Sentences::   Moving over and killing sentences.
* Paragraphs::	Moving over paragraphs.
* Pages::	Moving over pages.
* Filling::     Filling or justifying text
* Case::        Changing the case of text
@end menu

@node Text Mode, Words, Text, Text
@section Text Mode

@findex tab-to-tab-stop
@findex edit-tab-stops
@cindex Text mode
@kindex TAB
@findex text-mode
  You should use Text mode---rather than Fundamental or Lisp mode---to
edit files of text in a human language.  Invoke @kbd{M-x text-mode} to
enter Text mode.  In Text mode, @key{TAB} runs the function
@code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set
with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}).  Features concerned
with comments in programs are turned off unless they are explicitly invoked.
The syntax table is changed so that periods are not considered part of a
word, while apostrophes, backspaces and underlines are.

@findex indented-text-mode
  A similar variant mode is Indented Text mode, intended for editing
text in which most lines are indented.  This mode defines @key{TAB} to
run @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill
indent the lines it creates.  As a result, a line made by Auto Filling,
or by @key{LFD}, is normally indented just like the previous line.  Use
@kbd{M-x indented-text-mode} to select this mode.

@vindex text-mode-hook
  Entering Text mode or Indented Text mode calls the value of the
variable @code{text-mode-hook} with no arguments, if that value exists
and is not @code{nil}.  This value is also called when modes related to
Text mode are entered; this includes Nroff mode, @TeX{} mode, Outline
mode, and Mail mode.  Your hook can look at the value of
@code{major-mode} to see which of these modes is actually being entered.

  Two modes similar to Text mode are of use for editing text that is to
be passed through a text formatter before achieving its final readable form.

@menu
* Nroff Mode::  The major mode for editing input to the formatter nroff.
* TeX Mode::    The major modes for editing input to the formatter TeX.

  Another similar mode is used for editing outlines.  It allows you
to view the text at various levels of detail.  You can view either
the outline headings alone or both headings and text; you can also
hide some of the headings at lower levels from view to make the high
level structure more visible.

* Outline Mode:: The major mode for editing outlines.
@end menu

@node Nroff Mode, TeX Mode, Text Mode, Text Mode
@subsection Nroff Mode

@cindex nroff
@findex nroff-mode
  Nroff mode is a mode like Text mode but modified to handle nroff
commands present in the text.  Invoke @kbd{M-x nroff-mode} to enter this
mode.  Nroff mode differs from Text mode in only a few ways.  All nroff
command lines are considered paragraph separators, so that filling never
garbles the nroff commands.  Pages are separated by @samp{.bp} commands.
Comments start with backslash-doublequote.  There are also three special
commands that are not available in Text mode:

@findex forward-text-line
@findex backward-text-line
@findex count-text-lines
@kindex M-n
@kindex M-p
@kindex M-?
@table @kbd
@item M-n
Move to the beginning of the next line that isn't an nroff command
(@code{forward-text-line}).  An argument is a repeat count.
@item M-p
Like @kbd{M-n} but move up (@code{backward-text-line}).
@item M-?
Prints in the echo area the number of text lines (lines that are not
nroff commands) in the region (@code{count-text-lines}).
@end table

@findex electric-nroff-mode
  The other feature of Nroff mode is Electric Nroff newline mode.
This is a minor mode that you can turn on or off with
@kbd{M-x electric-nroff-mode} (@pxref{Minor Modes}).  When the mode is
on and you use @key{RET} to end a line containing an nroff command
that opens a kind of grouping, Emacs automatically inserts the matching
nroff command to close that grouping on the following line.  For
example, if you are at the beginning of a line and type @kbd{.@:(b
@key{RET}}, the matching command @samp{.)b} will be inserted on a new
line following point.

@vindex nroff-mode-hook
  Entering Nroff mode calls the value of the variable
@code{text-mode-hook} with no arguments, if that value exists and is not
@code{nil}; then it does the same with the variable
@code{nroff-mode-hook}.

@node TeX Mode, Outline Mode, Nroff Mode, Text Mode
@subsection @TeX{} Mode
@cindex TeX
@cindex LaTeX
@findex TeX-mode
@findex tex-mode
@findex plain-tex-mode
@findex LaTeX-mode
@findex plain-TeX-mode
@findex latex-mode

  @TeX{} is a powerful text formatter written by Donald Knuth; like GNU
Emacs, it is free.  La@TeX{} is a simplified input format for @TeX{},
implemented by @TeX{} macros.  It is part of @TeX{}.@refill

  Emacs has a special @TeX{} mode for editing @TeX{} input files.
It provides facilities for checking the balance of delimiters and for
invoking @TeX{} on all or part of the file.

  @TeX{} mode has two variants, Plain @TeX{} mode and La@TeX{} mode,
which are two distinct major modes that differ only slightly.  These
modes are designed for editing the two different input formats.  The
command @kbd{M-x tex-mode} looks at the contents of a buffer to
determine whether it appears to be La@TeX{} input or not; it then
selects the appropriate mode.  If it can't tell which is right (e.g.,
the buffer is empty), the variable @code{tex-default-mode} controls
which mode is used.

  The commands @kbd{M-x plain-tex-mode} and @kbd{M-x latex-mode}
explicitly select one of the variants of @TeX{} mode.  Use these
commands when @kbd{M-x tex-mode} does not guess right.@refill

@menu
* Editing: TeX Editing.   Special commands for editing in TeX mode.
* Printing: TeX Print.    Commands for printing part of a file with TeX.
@end menu

  @TeX{} for Unix systems can be obtained from the University of Washington
for a distribution fee.

  To order a full distribution, send $140.00 for a 1/2 inch
9-track tape, $165.00 for two 4-track 1/4 inch cartridge tapes
(foreign sites $150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover
the extra postage) payable to the University of Washington to:

@display
The Director
Northwest Computer Support Group,  DW-10
University of Washington
Seattle, Washington 98195
@end display

@noindent
Purchase orders are acceptable, but there is an extra charge of
$10.00 to pay for processing charges. (The total cost comes to $150
for domestic sites, $175 for foreign sites).

  The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
industry standard 2400 foot half-inch reel.  The physical format for
the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track
serpentine recording for the SUN.  Also, SystemV tapes can be written
in cpio format, blocked 5120 bytes, ASCII headers.

@node TeX Editing,TeX Print,TeX Mode,TeX Mode
@subsubsection @TeX{} Editing Commands

  Here are the special commands provided in @TeX{} mode for editing the
text of the file.

@table @kbd
@item "
Insert, according to context, either @samp{``} or @samp{"} or
@samp{''} (@code{TeX-insert-quote}).
@item @key{LFD}
Insert a paragraph break (two newlines) and check the previous
paragraph for unbalanced braces or dollar signs
(@code{tex-terminate-@*paragraph}).
@item M-x validate-tex-buffer
Check each paragraph in the buffer for unbalanced braces or dollar signs.
@item C-c @{
Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
@item C-c @}
Move forward past the next unmatched close brace (@code{up-list}).
@item C-c C-e
Close a block for La@TeX{} (@code{tex-close-latex-block}).
@end table

@findex tex-insert-quote
@kindex " (TeX mode)
  In @TeX{}, the character @samp{"} is not normally used; you use @samp{``}
to start a quotation and @samp{''} to end one.  @TeX{} mode defines the key
@kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"}
after a backslash, or @samp{''} otherwise.  This is done by the command
@code{tex-insert-quote}.  If you need the character @samp{"} itself in
unusual contexts, use @kbd{C-q} to insert it.  Also, @kbd{"} with a
numeric argument always inserts that number of @samp{"} characters.

  In @TeX{} mode, @samp{$} has a special syntax code which attempts to
understand the way @TeX{} math mode delimiters match.  When you insert a
@samp{$} that is meant to exit math mode, the position of the matching
@samp{$} that entered math mode is displayed for a second.  This is the
same feature that displays the open brace that matches a close brace that
is inserted.  However, there is no way to tell whether a @samp{$} enters
math mode or leaves it; so when you insert a @samp{$} that enters math
mode, the previous @samp{$} position is shown as if it were a match, even
though they are actually unrelated.

@findex tex-insert-braces
@kindex C-c @{ (TeX mode)
@findex up-list
@kindex C-c @} (TeX mode)
  If you prefer to keep braces balanced at all times, you can use @kbd{C-c @{}
(@code{tex-insert-braces}) to insert a pair of braces.  It leaves point
between the two braces so you can insert the text that belongs inside.
Afterward, use the command @kbd{C-c @}} (@code{up-list}) to move forward
past the close brace.

@findex validate-tex-buffer
@findex tex-terminate-paragraph
@kindex LFD (TeX mode)
  There are two commands for checking the matching of braces.  @key{LFD}
(@code{tex-terminate-paragraph}) checks the paragraph before point, and
inserts two newlines to start a new paragraph.  It prints a message in the
echo area if any mismatch is found.  @kbd{M-x validate-tex-buffer} checks
the entire buffer, paragraph by paragraph.  When it finds a paragraph that
contains a mismatch, it displays point at the beginning of the paragraph
for a few seconds and pushes a mark at that spot.  Scanning continues
until the whole buffer has been checked or until you type another key.
The positions of the last several paragraphs with mismatches can be
found in the mark ring (@pxref{Mark Ring}).

  Note that square brackets and parentheses, not just braces, are
matched in @TeX{} mode.  This is wrong if you want to  check @TeX{} syntax.
However, parentheses and square brackets are likely to be used in text as
matching delimiters and it is useful for the various motion commands and
automatic match display to work with them.

@findex tex-close-latex-block
@kindex C-c C-f (LaTeX mode)
  In La@TeX{} input, @samp{\begin} and @samp{\end} commands must balance.
After you insert a @samp{\begin}, use @kbd{C-c C-f}
(@code{tex-close-latex-block}) to insert automatically a matching
@samp{\end} (on a new line following the @samp{\begin}).  A blank line is
inserted between the two, and point is left there.@refill

@node TeX Print,,TeX Editing,TeX Mode
@subsubsection @TeX{} Printing Commands

  You can invoke @TeX{} as an inferior of Emacs on either the entire
contents of the buffer or just a region at a time.  Running @TeX{} in
this way on just one chapter is a good way to see what your changes
look like without taking the time to format the entire file.

@table @kbd
@item C-c C-r
Invoke @TeX{} on the current region, plus the buffer's header
(@code{tex-region}).
@item C-c C-b
Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
@item C-c C-l
Recenter the window showing output from the inferior @TeX{} so that
the last line can be seen (@code{tex-recenter-output-buffer}).
@item C-c C-k
Kill the inferior @TeX{} (@code{tex-kill-job}).
@item C-c C-p
Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command
(@code{tex-print}).
@item C-c C-q
Show the printer queue (@code{tex-show-print-queue}).
@end table

@findex tex-buffer
@kindex C-c C-b (TeX mode)
@findex tex-print
@kindex C-c C-p (TeX mode)
@findex tex-show-print-queue
@kindex C-c C-q (TeX mode)
  You can pass the current buffer through an inferior @TeX{} using
@kbd{C-c C-b} (@code{tex-buffer}).  The formatted output appears in a file
in @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{tex-print}).
Afterward use @kbd{C-c C-q} (@code{tex-show-print-queue}) to view the
progress of your output towards being printed.

@findex tex-kill-job
@kindex C-c C-k (TeX mode)
@findex tex-recenter-output-buffer
@kindex C-c C-l (TeX mode)
  The console output from @TeX{}, including any error messages, appears in a
buffer called @samp{*TeX-shell*}.  If @TeX{} gets an error, you can switch
to this buffer and feed it input (this works as in Shell mode;
@pxref{Interactive Shell}).  Without switching to this buffer, you can scroll
it so that its last line is visible by typing @kbd{C-c C-l}.

  Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
you see that its output is no longer useful.  Using @kbd{C-c C-b} or
@kbd{C-c C-r} also kills any @TeX{} process still running.@refill

@findex tex-region
@kindex C-c C-r (TeX mode)
  You can pass an arbitrary region through an inferior @TeX{} by typing
@kbd{C-c C-r} (@code{tex-region}).  This is tricky, however, because
most files of @TeX{} input contain commands at the beginning to set
parameters and define macros.  Without them, no later part of the file
will format correctly.  To solve this problem, @kbd{C-c C-r} allows you
to designate a part of the file as containing essential commands; it is
included before the specified region as part of the input to @TeX{}.
The designated part of the file is called the @dfn{header}.

@cindex header (TeX mode)
  To indicate the bounds of the header in Plain @TeX{} mode, insert two
special strings in the file: @samp{%**start of header} before the
header, and @samp{%**end of header} after it.  Each string must appear
entirely on one line, but there may be other text on the line before or
after.  The lines containing the two strings are included in the header.
If @samp{%**start of header} does not appear within the first 100 lines of
the buffer, @kbd{C-c C-r} assumes there is no header.

  In La@TeX{} mode, the header begins with @samp{\documentstyle} and ends
with @*@samp{\begin@{document@}}.  These are commands that La@TeX{} requires
you to use, so you don't need to do anything special to identify the
header.

@vindex TeX-mode-hook
@vindex LaTeX-mode-hook
@vindex plain-TeX-mode-hook
  When you enter either kind of @TeX{} mode, Emacs calls with no
arguments the value of the variable @code{text-mode-hook}, if that value
exists and is not @code{nil}.  Emacs then calls the variable
@code{TeX-mode-hook} and either @code{plain-TeX-mode-hook} or
@code{LaTeX-mode-hook} under the same conditions.

@node Outline Mode,, TeX Mode, Text Mode
@subsection Outline Mode
@cindex outlines
@cindex selective display
@cindex invisible lines

  Outline mode is a major mode similar to Text mode but intended for editing
outlines.  It allows you to make parts of the text temporarily invisible
so that you can see just the overall structure of the outline.  Type
@kbd{M-x outline-mode} to turn on Outline mode in the current buffer.

@vindex outline-mode-hook
  When you enter Outline mode, Emacs calls with no arguments the value
of the variable @code{text-mode-hook}, if that value exists and is not
@code{nil}; then it does the same with the variable
@code{outline-mode-hook}.

  When a line is invisible in outline mode, it does not appear on the
screen.  The screen appears exactly as if the invisible line
were deleted, except that an ellipsis (three periods in a row) appears
at the end of the previous visible line (only one ellipsis no matter
how many invisible lines follow).

  All editing commands treat the text of the invisible line as part of the
previous visible line.  For example, @kbd{C-n} moves onto the next visible
line.  Killing an entire visible line, including its terminating newline,
really kills all the following invisible lines as well; yanking
everything back yanks the invisible lines and they remain invisible.

@menu
* Format: Outline Format.	  What the text of an outline looks like.
* Motion: Outline Motion.	  Special commands for moving through outlines.
* Visibility: Outline Visibility. Commands to control what is visible.
@end menu

@node Outline Format,Outline Motion,Outline Mode, Outline Mode
@subsubsection Format of Outlines

@cindex heading lines (Outline mode)
@cindex body lines (Outline mode)
  Outline mode assumes that the lines in the buffer are of two types:
@dfn{heading lines} and @dfn{body lines}.  A heading line represents a
topic in the outline.  Heading lines start with one or more stars; the
number of stars determines the depth of the heading in the outline
structure.  Thus, a heading line with one star is a major topic; all the
heading lines with two stars between it and the next one-star heading
are its subtopics; and so on.  Any line that is not a heading line is a
body line.  Body lines belong to the preceding heading line.  Here is an
example:

@example
* Food

This is the body,
which says something about the topic of food.

** Delicious Food

This is the body of the second-level header.

** Distasteful Food

This could have
a body too, with
several lines.

*** Dormitory Food

* Shelter

A second first-level topic with its header line.
@end example

  A heading line together with all following body lines is called
collectively an @dfn{entry}.  A heading line together with all following
deeper heading lines and their body lines is called a @dfn{subtree}.

@vindex outline-regexp
 You can customize the criterion for distinguishing heading lines by
setting the variable @code{outline-regexp}.  Any line whose beginning
has a match for this regexp is considered a heading line.  Matches that
start within a line (not at the beginning) do not count.  The length of
the matching text determines the level of the heading; longer matches
make a more deeply nested level.  Thus, for example, if a text formatter
has commands @samp{@@chapter}, @samp{@@section} and @samp{@@subsection}
to divide the document into chapters and sections, you can make those
lines count as heading lines by setting @code{outline-regexp} to
@samp{"@@chap\\|@@\\(sub\\)*section"}.  Note the trick: the two words
@samp{chapter} and @samp{section} are the same length, but by defining
the regexp to match only @samp{chap} we ensure that the length of the
text matched on a chapter heading is shorter, so that Outline mode will
know that sections are contained in chapters.  This works as long as no
other command starts with @samp{@@chap}.

  Outline mode makes a line invisible by changing the newline before it
into an ASCII Control-M (code 015).  Most editing commands that work on
lines treat an invisible line as part of the previous line because,
strictly speaking, it @i{is} part of that line, since there is no longer a
newline in between.  When you save the file in Outline mode, Control-M
characters are saved as newlines, so the invisible lines become ordinary
lines in the file.  Saving does not change the visibility status of a
line inside Emacs.

@node Outline Motion,Outline Visibility,Outline Format,Outline Mode
@subsubsection Outline Motion Commands

   Some special commands in Outline mode move backward and forward to
heading lines.

@table @kbd
@item C-c C-n
Move point to the next visible heading line
(@code{outline-next-visible-heading}).
@item C-c C-p
Move point to the previous visible heading line @*
(@code{outline-previous-visible-heading}).
@item C-c C-f
Move point to the next visible heading line at the same level
as the one point is on (@code{outline-forward-same-level}).
@item C-c C-b
Move point to the previous visible heading line at the same level
(@code{outline-backward-same-level}).
@item C-c C-u
Move point up to a lower-level (more inclusive) visible heading line
(@code{outline-up-heading}).
@end table

@findex outline-next-visible-heading
@findex outline-previous-visible-heading
@kindex C-c C-n (Outline mode)
@kindex C-c C-p (Outline mode)
  @kbd{C-c C-n} (@code{next-visible-heading}) moves down to the next
heading line.  @kbd{C-c C-p} (@code{previous-visible-heading}) moves
similarly backward.  Both accept numeric arguments as repeat counts.  The
names emphasize that invisible headings are skipped, but this is not really
a special feature.  All editing commands that look for lines ignore the
invisible lines automatically.@refill

@findex outline-up-heading
@findex outline-forward-same-level
@findex outline-backward-same-level
@kindex C-c C-f (Outline mode)
@kindex C-c C-b (Outline mode)
@kindex C-c C-u (Outline mode)
  More advanced motion commands understand the levels of headings.
The commands @kbd{C-c C-f} (@code{outline-forward-same-level}) and
@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
heading line to another visible heading at the same depth in
the outline.  @kbd{C-c C-u} (@code{outline-up-heading}) moves
backward to another heading that is less deeply nested.

@node Outline Visibility,,Outline Motion,Outline Mode
@subsubsection Outline Visibility Commands

  The other special commands of outline mode are used to make lines visible
or invisible.  Their names all start with @code{hide} or @code{show}.
Most of them exist as pairs of opposites.  They are not undoable; instead,
you can undo right past them.  Making lines visible or invisible is simply
not recorded by the undo mechanism.

@table @kbd
@item M-x hide-body
Make all body lines in the buffer invisible.
@item M-x show-all
Make all lines in the buffer visible.
@item C-c C-d
Make everything under this heading invisible, not including this
heading itself (@code{hide-subtree}).
@item C-c C-s
Make everything under this heading visible, including body,
subheadings, and their bodies (@code{show-subtree}).
@item M-x hide-leaves
Make the body of this heading line, and of all its subheadings,
invisible.
@item M-x show-branches
Make all subheadings of this heading line, at all levels, visible.
@item C-c C-i
Make immediate subheadings (one level down) of this heading line
visible (@code{show-children}).
@item M-x hide-entry
Make this heading line's body invisible.
@item M-x show-entry
Make this heading line's body visible.
@end table

@findex hide-entry
@findex show-entry
  Two commands that are exact opposites are @kbd{M-x hide-entry} and
@kbd{M-x show-entry}.  They are used with point on a heading line, and
apply only to the body lines of that heading.  The subtopics and their
bodies are not affected.

@findex hide-subtree
@findex show-subtree
@kindex C-c C-d (Outline mode)
@kindex C-c C-h (Outline mode)
@cindex subtree (Outline mode)
  Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and
@kbd{C-c C-s} (@code{show-subtree}).  Both should be used when point is
on a heading line, and both apply to all the lines of that heading's
@dfn{subtree}: its body, all its subheadings, both direct and indirect, and
all of their bodies.  In other words, the subtree contains everything
following this heading line, up to and not including the next heading of
the same or higher rank.@refill

@findex hide-leaves
@findex show-branches
  Intermediate between a visible subtree and an invisible one is having
all the subheadings visible but none of the body.  There are two commands
for doing this, one that hides the bodies and one that
makes the subheadings visible.  They are @kbd{M-x hide-leaves} and
@kbd{M-x show-branches}.

@kindex C-c C-i (Outline mode)
@findex show-children
  A little weaker than @code{show-branches} is @kbd{C-c C-i}
(@code{show-children}).  It makes just the direct subheadings
visible---those one level down.  Deeper subheadings remain
invisible.@refill

@findex hide-body
@findex show-all
  Two commands have a blanket effect on the whole file.  @kbd{M-x
hide-body} makes all body lines invisible, so that you see just the
outline structure.  @kbd{M-x show-all} makes all lines visible.  You can
think of these commands as a pair of opposites even though @kbd{M-x
show-all} applies to more than just body lines.

@vindex selective-display-ellipses
You can turn off the use of ellipses at the ends of visible lines by
setting @code{selective-display-ellipses} to @code{nil}.  The result is
no visible indication of the presence of invisible lines.

@node Words, Sentences, Text Mode, Text
@section Words
@cindex words
@cindex Meta

  Emacs has commands for moving over or operating on words.  By convention,
the keys for them are all @kbd{Meta-} characters.

@c widecommands
@table @kbd
@item M-f
Move forward over a word (@code{forward-word}).
@item M-b
Move backward over a word (@code{backward-word}).
@item M-d
Kill up to the end of a word (@code{kill-word}).
@item M-@key{DEL}
Kill back to the beginning of a word (@code{backward-kill-word}).
@item M-@@
Mark the end of the next word (@code{mark-word}).
@item M-t
Transpose two words;  drag a word forward
or backward across other words (@code{transpose-words}).
@end table

  Notice how these keys form a series that parallels the
character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and
@key{DEL}.  @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for
@kbd{C-@key{SPC}}.@refill

@kindex M-f
@kindex M-b
@findex forward-word
@findex backward-word
  The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b}
(@code{backward-word}) move forward and backward over words.  They are
analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single
characters.  Like their @kbd{Control-} analogues, @kbd{Meta-f} and
@kbd{Meta-b} move several words if given an argument.  @kbd{Meta-f} with a
negative argument moves backward, and @kbd{Meta-b} with a negative argument
moves forward.  Forward motion stops after the last letter of the
word, while backward motion stops before the first letter.@refill

@kindex M-d
@findex kill-word
  @kbd{Meta-d} (@code{kill-word}) kills the word after point.  To be
precise, it kills everything from point to the place @kbd{Meta-f} would
move to.  Thus, if point is in the middle of a word, @kbd{Meta-d} kills
just the part after point.  If some punctuation comes between point and the
next word, it is killed along with the word.  (To kill only the
next word but not the punctuation before it, simply type @kbd{Meta-f} to get
to the end and kill the word backwards with @kbd{Meta-@key{DEL}}.)
@kbd{Meta-d} takes arguments just like @kbd{Meta-f}.

@findex backward-kill-word
@kindex M-DEL
  @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before
point.  It kills everything from point back to where @kbd{Meta-b} would
move to.  If point is after the space in @w{@samp{FOO, BAR}}, then
@w{@samp{FOO, }} is killed.   To kill just @samp{FOO}, type
@kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.

@cindex transposition
@kindex M-t
@findex transpose-words
  @kbd{Meta-t} (@code{transpose-words}) exchanges the word before or
containing point with the following word.  The delimiter characters
between the words do not move.  For example, transposing @w{@samp{FOO,
BAR}} results in @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
@xref{Transpose}, for more on transposition and on arguments to
transposition commands.

@kindex M-@@
@findex mark-word
  To operate on the next @var{n} words with an operation which applies
between point and mark, you can either set the mark at point and then move
over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word})
which does not move point but sets the mark where @kbd{Meta-f} would move
to.  It can be given arguments just like @kbd{Meta-f}.

@cindex syntax table
  The word commands' understanding of syntax is completely controlled by
the syntax table.  For example, any character can be declared to be a word
delimiter.  @xref{Syntax}.

@node Sentences, Paragraphs, Words, Text
@section Sentences
@cindex sentences

  The Emacs commands for manipulating sentences and paragraphs are mostly
on @kbd{Meta-} keys, and therefore are like the word-handling commands.

@table @kbd
@item M-a
Move back to the beginning of the sentence (@code{backward-sentence}).
@item M-e
Move forward to the end of the sentence (@code{forward-sentence}).
@item M-k
Kill forward to the end of the sentence (@code{kill-sentence}).
@item C-x @key{DEL}
Kill back to the beginning of the sentence @*(@code{backward-kill-sentence}).
@end table

@kindex M-a
@kindex M-e
@findex backward-sentence
@findex forward-sentence
  The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence}
and @code{forward-sentence}) move to the beginning and end of the
current sentence, respectively.  They resemble @kbd{Control-a} and
@kbd{Control-e}, which move to the beginning and end of a line.  Unlike
their counterparts, @kbd{Meta-a} and @kbd{Meta-e} move over successive
sentences if repeated or given numeric arguments.  Emacs assumes
the typist's convention is followed, and thus considers a sentence to
end wherever there is a @samp{.}, @samp{?}, or @samp{!} followed by the
end of a line or two spaces, with any number of @samp{)}, @samp{]},
@samp{'}, or @samp{"} characters allowed in between.  A sentence also
begins or ends wherever a paragraph begins or ends.@refill

  Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond
the sentence edge at which it is stopping.

@kindex M-k
@kindex C-x DEL
@findex kill-sentence
@findex backward-kill-sentence
 @kbd{M-a} and @kbd{M-e} have a corresponding kill command, just like
@kbd{C-a} and @kbd{C-e} have @kbd{C-k}.  The command is  @kbd{M-k}
(@code{kill-sentence}) which kills from point to the end of the
sentence.  With minus one as an argument it kills back to the beginning
of the sentence.  Larger arguments serve as repeat counts.@refill

  There is a special command, @kbd{C-x @key{DEL}}
(@code{backward-kill-sentence}), for killing back to the beginning of a
sentence, which is useful when you change your mind in the middle of
composing text.@refill

@vindex sentence-end
  The variable @code{sentence-end} controls recognition of the end of a
sentence.  It is a regexp that matches the last few characters of a
sentence, together with the whitespace following the sentence.  Its
normal value is:

@example
"[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
@end example

@noindent
This example is explained in the section on regexps.  @xref{Regexps}.

@node Paragraphs, Pages, Sentences, Text
@section Paragraphs
@cindex paragraphs
@kindex M-@{
@kindex M-@}
@findex backward-paragraph
@findex forward-paragraph

  The Emacs commands for manipulating paragraphs are also @kbd{Meta-}
keys.

@table @kbd
@item M-@{
Move back to previous paragraph beginning @*(@code{backward-paragraph}).
@item M-@}
Move forward to next paragraph end (@code{forward-paragraph}).
@item M-h
Put point and mark around this or next paragraph (@code{mark-paragraph}).
@end table

  @kbd{Meta-@{} moves to the beginning of the current or previous paragraph,
while @kbd{Meta-@}} moves to the end of the current or next paragraph.
Blank lines and text formatter command lines separate paragraphs and are
not part of any paragraph.  An indented line starts a new paragraph.

  In major modes for programs (as opposed to Text mode), paragraphs begin
and end only at blank lines.  As a result, the paragraph commands continue to
be useful even though there are no paragraphs per se.

  When there is a fill prefix, paragraphs are delimited by all lines
which don't start with the fill prefix.  @xref{Filling}.

@kindex M-h
@findex mark-paragraph
   To operate on a paragraph, you can use the command
@kbd{Meta-h} (@code{mark-paragraph}) to set the region around it.  This
command puts point at the beginning and mark at the end of the paragraph
point was in.  If point is between paragraphs (in a run of blank lines or
at a boundary), the paragraph following point is surrounded by point and
mark.  If there are blank lines preceding the first line of the paragraph,
one of the blank lines is included in the region.  Thus, for example,
@kbd{M-h C-w} kills the paragraph around or after point.

@vindex paragraph-start
@vindex paragraph-separate
  The precise definition of a paragraph boundary is controlled by the
variables @code{paragraph-separate} and @code{paragraph-start}.  The value
of @code{paragraph-start} is a regexp that matches any line that
either starts or separates paragraphs.  The value of
@code{paragraph-separate} is another regexp that  matches only lines
that separate paragraphs without being part of any paragraph.  Lines that
start a new paragraph and are contained in it must match both regexps.  For
example, normally @code{paragraph-start} is @code{"^[ @t{\}t@t{\}n@t{\}f]"}
and @code{paragraph-separate} is @code{"^[ @t{\}t@t{\}f]*$"}.@refill

  Normally it is desirable for page boundaries to separate paragraphs.
The default values of these variables recognize the usual separator for
pages.

@node Pages, Filling, Paragraphs, Text
@section Pages

@cindex pages
@cindex formfeed
  Files are often thought of as divided into @dfn{pages} by the
@dfn{formfeed} character (ASCII Control-L, octal code 014).  For
example, if a file is printed on a line printer, each ``page'' of the
file starts on a new page of paper.  Emacs treats a page-separator
character just like any other character.  It can be inserted with
@kbd{C-q C-l} or deleted with @key{DEL}.  You are free to
paginate your file or not.  However, since pages are often meaningful
divisions of the file, commands are provided to move over them and
operate on them.

@c WideCommands
@table @kbd
@item C-x [
Move point to previous page boundary (@code{backward-page}).
@item C-x ]
Move point to next page boundary (@code{forward-page}).
@item C-x C-p
Put point and mark around this page (or another page) (@code{mark-page}).
@item C-x l
Count the lines in this page (@code{count-lines-page}).
@end table

@kindex C-x [
@kindex C-x ]
@findex forward-page
@findex backward-page
  The @kbd{C-x [} (@code{backward-page}) command moves point to
immediately after the previous page delimiter.  If point is already
right after a page delimiter, the command skips that one and stops at
the previous one.  A numeric argument serves as a repeat count.  The
@kbd{C-x ]} (@code{forward-page}) command moves forward past the next
page delimiter.

@kindex C-x C-p
@findex mark-page
  The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning
of the current page and the mark at the end.  The page delimiter at the end
is included (the mark follows it).  The page delimiter at the front is
excluded (point follows it).  You can follow this command  by @kbd{C-w} to
kill a page you want to move elsewhere.  If you insert the page after a page
delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you,
the page will be properly delimited before and after once again.

  A numeric argument to @kbd{C-x C-p} is used to specify which page to go
to, relative to the current one.  Zero means the current page.  One means
the next page, and @minus{}1 means the previous one.

@kindex C-x l
@findex count-lines-page
  The @kbd{C-x l} command (@code{count-lines-page}) can help you decide
where to break a page in two.  It prints the total number of lines in
the current page in the echo area, then divides the lines into those
preceding the current line and those following it, for example

@example
Page has 96 (72+25) lines
@end example

@noindent
  Notice that the sum is off by one; this is correct if point is not at the
beginning of a line.

@vindex page-delimiter
  The variable @code{page-delimiter} should have as its value a regexp that
matches the beginning of a line that separates pages.  This defines
where pages begin.  The normal value of this variable is @code{"^@t{\}f"},
which matches a formfeed character at the beginning of a line.

@node Filling, Case, Pages, Text
@section Filling Text
@cindex filling

  If you use Auto Fill mode, Emacs @dfn{fills} text (breaks it up into
lines that fit in a specified width) as you insert it.  When you alter
existing text it is often no longer be properly filled afterwards and
you can use explicit commands for filling.

@menu
* Auto Fill::	  Auto Fill mode breaks long lines automatically.
* Fill Commands:: Commands to refill paragraphs and center lines.
* Fill Prefix::   Filling when every line is indented or in a comment, etc.
@end menu

@node Auto Fill, Fill Commands, Filling, Filling
@subsection Auto Fill Mode

@cindex Auto Fill mode

  @dfn{Auto Fill} mode is a minor mode in which lines are broken
automatically when they become too wide.  Breaking happens only when
you type a @key{SPC} or @key{RET}.

@table @kbd
@item M-x auto-fill-mode
Enable or disable Auto Fill mode.
@item @key{SPC}
@itemx @key{RET}
In Auto Fill mode, break lines when appropriate.
@end table

@findex auto-fill-mode
  @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
if it was on.  With a positive numeric argument the command always turns
Auto Fill mode on, and with a negative argument it always turns it off.
The presence of the word @samp{Fill} in the mode line, inside the
parentheses, indicates that Auto Fill mode is in effect.  Auto Fill mode
is a minor mode; you can turn it on or off for each buffer individually.
@xref{Minor Modes}.

  In Auto Fill mode, lines are broken automatically at spaces when they get
longer than desired.  Line breaking and rearrangement takes place
only when you type @key{SPC} or @key{RET}.  To insert a space
or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or
@kbd{C-q @key{LFD}} (recall that a newline is really a linefeed).
@kbd{C-o} inserts a newline without line breaking.

  Auto Fill mode works well with Lisp mode: when it makes a new line in
Lisp mode, it indents that line with @key{TAB}.  If a line ending in a
Lisp comment gets too long, the text of the comment is split into two
comment lines.  Optionally, new comment delimiters are inserted at the
end of the first line and the beginning of the second, so that each line
is a separate comment.  The variable @code{comment-multi-line} controls
the choice (@pxref{Comments}).

  Auto Fill mode does not refill entire paragraphs.  It can break lines but
cannot merge lines.  Editing in the middle of a paragraph can result in
a paragraph that is not correctly filled.  The easiest way to make the
paragraph properly filled again is using an explicit fill commands.

  Many users like Auto Fill mode and want to use it in all text files.
The section on init files explains how you can arrange this
permanently for yourself.  @xref{Init File}.

@node Fill Commands, Fill Prefix, Auto Fill, Filling
@subsection Explicit Fill Commands

@table @kbd
@item M-q
Fill current paragraph (@code{fill-paragraph}).
@item M-g
Fill each paragraph in the region (@code{fill-region}).
@item C-x f
Set the fill column (@code{set-fill-column}).
@item M-x fill-region-as-paragraph
Fill the region, considering it as one paragraph.
@item M-s
Center a line.
@end table

@kindex M-q
@findex fill-paragraph
  To refill a paragraph, use the command @kbd{Meta-q}
(@code{fill-paragraph}).  It causes the paragraph containing point, or
the one after point if point is between paragraphs, to be refilled.  All
line breaks are removed, and new ones are inserted where necessary.
@kbd{M-q} can be undone with @kbd{C-_}.  @xref{Undo}.@refill

@kindex M-g
@findex fill-region
  To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which
divides the region into paragraphs and fills each of them.

@findex fill-region-as-paragraph
  @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h} for
finding paragraph boundaries (@pxref{Paragraphs}).  For more control, you
can use @kbd{M-x fill-region-as-paragraph}, which refills everything
between point and mark.  This command recognizes only blank lines as
paragraph separators.@refill

@cindex justification
  A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to
@dfn{justify} the text as well as filling it.  Extra spaces are inserted
to make the right margin line up exactly at the fill column.  To remove
the extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill

@vindex auto-fill-inhibit-regexp
The variable @code{auto-fill-inhibit-regexp} takes as a value a regexp to
match lines that should not be auto-filled.

@kindex M-s
@cindex centering
@findex center-line
  The command @kbd{Meta-s} (@code{center-line}) centers the current line
within the current fill column.  With an argument, it centers several lines
individually and moves past them.

@vindex fill-column
  The maximum line width for filling is in the variable
@code{fill-column}.  Altering the value of @code{fill-column} makes it
local to the current buffer; until then, the default value---initially
70---is in effect. @xref{Locals}.

@kindex C-x f
@findex set-fill-column
  The easiest way to set @code{fill-column} is to use the command @kbd{C-x
f} (@code{set-fill-column}).  With no argument, it sets @code{fill-column}
to the current horizontal position of point.  With a numeric argument, it
uses that number as the new fill column.

@node Fill Prefix,, Fill Commands, Filling
@subsection The Fill Prefix

@cindex fill prefix
  To fill a paragraph in which each line starts with a special marker
(which might be a few spaces, giving an indented paragraph), use the
@dfn{fill prefix} feature.  The fill prefix is a string which is not
included in filling.  Emacs expects every line to start with a fill
prefix.

@table @kbd
@item C-x .
Set the fill prefix (@code{set-fill-prefix}).
@item M-q
Fill a paragraph using current fill prefix (@code{fill-paragraph}).
@item M-x fill-individual-paragraphs
Fill the region, considering each change of indentation as starting a
new paragraph.
@end table

@kindex C-x .
@findex set-fill-prefix
  To specify a fill prefix, move to a line that starts with the desired
prefix, put point at the end of the prefix, and give the command
@w{@kbd{C-x .}}@: (@code{set-fill-prefix}).  That's a period after the
@kbd{C-x}.  To turn off the fill prefix, specify an empty prefix: type
@w{@kbd{C-x .}}@: with point at the beginning of a line.@refill

  When a fill prefix is in effect, the fill commands remove the fill
prefix from each line before filling and insert it on each line after
filling.  Auto Fill mode also inserts the fill prefix inserted on new
lines it creates.  Lines that do not start with the fill prefix are
considered to start paragraphs, both in @kbd{M-q} and the paragraph
commands; this is just right if you are using paragraphs with hanging
indentation (every line indented except the first one).  Lines which are
blank or indented once the prefix is removed also separate or start
paragraphs; this is what you want if you are writing multi-paragraph
comments with a comment delimiter on each line.

@vindex fill-prefix
  The fill prefix is stored in the variable @code{fill-prefix}.  Its value
is a string, or @code{nil} when there is no fill prefix.  This is a
per-buffer variable; altering the variable affects only the current buffer,
but there is a default value which you can change as well.  @xref{Locals}.

@findex fill-individual-paragraphs
  Another way to use fill prefixes is through @kbd{M-x
fill-individual-paragraphs}.  This function divides the region into groups
of consecutive lines with the same amount and kind of indentation and fills
each group as a paragraph, using its indentation as a fill prefix.

@node Case,, Filling, Text
@section Case Conversion Commands
@cindex case conversion

  Emacs has commands for converting either a single word or any arbitrary
range of text to upper case or to lower case.

@c WideCommands
@table @kbd
@item M-l
Convert following word to lower case (@code{downcase-word}).
@item M-u
Convert following word to upper case (@code{upcase-word}).
@item M-c
Capitalize the following word (@code{capitalize-word}).
@item C-x C-l
Convert region to lower case (@code{downcase-region}).
@item C-x C-u
Convert region to upper case (@code{upcase-region}).
@end table

@kindex M-l
@kindex M-u
@kindex M-c
@cindex words
@findex downcase-word
@findex upcase-word
@findex capitalize-word
  The word conversion commands are used most frequently.  @kbd{Meta-l}
(@code{downcase-word}) converts the word after point to lower case,
moving past it.  Thus, repeating @kbd{Meta-l} converts successive words.
@kbd{Meta-u} (@code{upcase-word}) converts to all capitals instead,
while @kbd{Meta-c} (@code{capitalize-word}) puts the first letter of the
word into upper case and the rest into lower case.  The word conversion
commands convert several words at once if given an argument.  They are
especially convenient for converting a large amount of text from all
upper case to mixed case: you can move through the text using
@kbd{M-l}, @kbd{M-u}, or @kbd{M-c} on each word as appropriate,
occasionally using @kbd{M-f} instead to skip a word.

  When given a negative argument, the word case conversion commands apply
to the appropriate number of words before point, but do not move point.
This is convenient when you have just typed a word in the wrong case: you
can give the case conversion command and continue typing.

  If a word case conversion command is given in the middle of a word, it
applies only to the part of the word which follows point.  This is just
like what @kbd{Meta-d} (@code{kill-word}) does.  With a negative argument,
case conversion applies only to the part of the word before point.

@kindex C-x C-l
@kindex C-x C-u
@cindex region
@findex downcase-region
@findex upcase-region
  The other case conversion commands are @kbd{C-x C-u}
(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
convert everything between point and mark to the specified case.  Point and
mark do not move.@refill


code:
@iftex
@chapter Correcting Mistakes (Yours or Emacs's)

  If you type an Emacs command you did not intend, the results are often
mysterious.  This chapter discusses how you can undo your mistake or
recover from a mysterious situation.  Emacs bugs and system crashes are
also considered.
@end iftex

@node Quitting, Lossage, Customization, Top
@section Quitting and Aborting
@cindex quitting

@table @kbd
@item C-g
Quit.  Cancel running or partially typed command.
@item C-]
Abort innermost recursive editing level and cancel the command which
invoked it (@code{abort-recursive-edit}).
@item M-x top-level
Abort all recursive editing levels that are currently executing.
@item C-x u
Cancel an already-executed command, usually (@code{undo}).
@end table

  There are two ways of cancelling commands which are not finished
executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
or @kbd{M-x top-level}.  Quitting is cancelling a partially typed command
or one which is already running.  Aborting is getting out of a recursive
editing level and cancelling the command that invoked the recursive edit.

@cindex quitting
@kindex C-g
  Quitting with @kbd{C-g} is used for getting rid of a partially typed
command or a numeric argument that you don't want.  It also stops a
running command in the middle in a relatively safe way, so you can use
it if you accidentally start executing a command that takes a long
time.  In particular, it is safe to quit out of killing; either your
text will @var{all} still be there, or it will @var{all} be in the kill
ring (or maybe both).  Quitting an incremental search does special
things documented under searching; in general, it may take two
successive @kbd{C-g} characters to get out of a search.  @kbd{C-g} works
by setting the variable @code{quit-flag} to @code{t} the instant
@kbd{C-g} is typed; Emacs Lisp checks this variable frequently and quits
if it is non-@code{nil}.  @kbd{C-g} is only actually executed as a
command if it is typed while Emacs is waiting for input.

If you quit twice in a row before the first @kbd{C-g} is recognized, you
activate the ``emergency escape'' feature and return to the shell.
@xref{Emergency Escape}.

@cindex recursive editing level
@cindex editing level, recursive
@cindex aborting
@findex abort-recursive-edit
@kindex C-]
  You can use @kbd{C-]} (@code{abort-recursive-edit}) to get out
of a recursive editing level and cancel the command which invoked it.
Quitting with @kbd{C-g} does not do this, and could not do this because it
is used to cancel a partially typed command @i{within} the recursive
editing level.  Both operations are useful.  For example, if you are in the
Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
numeric argument, you can cancel that argument with @kbd{C-g} and remain in
the debugger.

@findex top-level
  The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
commands to get you out of all the levels of recursive edits that you are
in.  @kbd{C-]} only gets you out one level at a time, but @kbd{M-x top-level}
goes out all levels at once.  Both @kbd{C-]} and @kbd{M-x top-level} are
like all other commands and unlike @kbd{C-g} in that they are effective
only when Emacs is ready for a command.  @kbd{C-]} is an ordinary key and
has its meaning only because of its binding in the keymap.
@xref{Recursive Edit}.

  @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a
command, but you can think of it as cancelling a command already finished
executing.  @xref{Undo}.

@node Lossage, Bugs, Quitting, Top
@section Dealing With Emacs Trouble

  This section describes various conditions in which Emacs fails to work,
and how to recognize them and correct them.

@menu
* Stuck Recursive::    `[...]' in mode line around the parentheses.
* Screen Garbled::     Garbage on the screen.
* Text Garbled::       Garbage in the text.
* Unasked-for Search:: Spontaneous entry to incremental search.
* Emergency Escape::   Emergency escape---
                        What to do if Emacs stops responding.
* Total Frustration::  When you are at your wits' end.
@end menu

@node Stuck Recursive, Screen Garbled, Lossage, Lossage
@subsection Recursive Editing Levels

  Recursive editing levels are important and useful features of Emacs, but
they can seem like malfunctions to the user who does not understand them.

  If the mode line has square brackets @samp{[@dots{}]} around the parentheses
that contain the names of the major and minor modes, you have entered a
recursive editing level.  If you did not do this on purpose, or if you
don't understand what that means, you should just get out of the recursive
editing level.  To do so, type @kbd{M-x top-level}.  This is called getting
back to top level.  @xref{Recursive Edit}.

@node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
@subsection Garbage on the Screen

  If the data on the screen looks wrong, the first thing to do is see
whether the text is actually wrong.  Type @kbd{C-l}, to redisplay the
entire screen.  If the text appears correct after this, the problem was
entirely in the previous screen update.

  Display updating problems often result from an incorrect termcap entry
for the terminal you are using.  The file @file{etc/TERMS} in the Emacs
distribution gives the fixes for known problems of this sort.
@file{INSTALL} contains general advice for these problems in one of its
sections.  Very likely there is simply insufficient padding for certain
display operations.  To investigate the possibility that you have this
sort of problem, try Emacs on another terminal made by a different
manufacturer.  If problems happen frequently on one kind of terminal but
not another kind, the real problem is likely to be a bad termcap entry,
though it could also be due to a bug in Emacs that appears for terminals
that have or lack specific features.

@node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
@subsection Garbage in the Text

  If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
using @kbd{C-x u} until it gets back to a state you consider correct.  Also
try @kbd{C-h l} to find out what command you typed to produce the observed
results.

  If a large portion of text appears to be missing at the beginning or
end of the buffer, check for the word @samp{Narrow} in the mode line.
If it appears, the text is still present, but marked off-limits.
To make it visible again, type @kbd{C-x n w}.  @xref{Narrowing}.

@node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
@subsection Spontaneous Entry to Incremental Search

  If Emacs spontaneously displays @samp{I-search:} at the bottom of the
screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
according to the poorly designed xon/xoff ``flow control'' protocol.  You
should try to prevent this by putting the terminal in a mode where it will
not use flow control, or by giving it enough padding that it will never send a
@kbd{C-s}.  If that cannot be done, you must tell Emacs to expect flow
control to be used, until you can get a properly designed terminal.

  Information on how to do these things can be found in the file
@file{INSTALL} in the Emacs distribution.

@node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
@subsection Emergency Escape

  Because at times there have been bugs causing Emacs to loop without
checking @code{quit-flag}, a special feature causes Emacs to be suspended
immediately if you type a second @kbd{C-g} while the flag is already set,
so you can always get out of XEmacs.  Normally Emacs recognizes and
clears @code{quit-flag} (and quits!) quickly enough to prevent this from
happening.

  When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
asks two questions before going back to what it had been doing:

@example
Auto-save? (y or n)
Abort (and dump core)? (y or n)
@end example

@noindent
Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.

  Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
modified buffers in which auto-saving is enabled.

  Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal
instruction to be executed, dumping core.  This is to enable a wizard to
figure out why Emacs was failing to quit in the first place.  Execution
does not continue after a core dump.  If you answer @kbd{n}, execution
does continue.  With luck, Emacs will ultimately check
@code{quit-flag} and quit normally.  If not, and you type another
@kbd{C-g}, it is suspended again.

  If Emacs is not really hung, but is just being slow, you may invoke
the double @kbd{C-g} feature without really meaning to.  In that case,
simply resume and answer @kbd{n} to both questions, and you will arrive
at your former state.  Presumably the quit you requested will happen
soon.

  The double-@kbd{C-g} feature may be turned off when Emacs is running under
a window system, since the window system always enables you to kill Emacs
or to create another window and run another program.

@node Total Frustration,, Emergency Escape, Lossage
@subsection Help for Total Frustration
@cindex Eliza
@cindex doctor

  If using Emacs (or something else) becomes terribly frustrating and none
of the techniques described above solve the problem, Emacs can still help
you.

  First, if the Emacs you are using is not responding to commands, type
@kbd{C-g C-g} to get out of it and then start a new one.

@findex doctor
  Second, type @kbd{M-x doctor @key{RET}}.

  The doctor will make you feel better.  Each time you say something to
the doctor, you must end it by typing @key{RET} @key{RET}.  This lets the
doctor know you are finished.

@node Bugs,, Lossage, Top
@section Reporting Bugs

@cindex bugs
  Sometimes you will encounter a bug in Emacs.  Although we cannot promise
we can or will fix the bug, and we might not even agree that it is a bug,
we want to hear about bugs you encounter in case we do want to fix them.

  To make it possible for us to fix a bug, you must report it.  In order
to do so effectively, you must know when and how to do it.

@subsection When Is There a Bug

  If Emacs executes an illegal instruction, or dies with an operating
system error message that indicates a problem in the program (as opposed to
something like ``disk full''), then it is certainly a bug.

  If Emacs updates the display in a way that does not correspond to what is
in the buffer, then it is certainly a bug.  If a command seems to do the
wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
case of incorrect display updating.

  Taking forever to complete a command can be a bug, but you must make
certain that it was really Emacs's fault.  Some commands simply take a long
time.  Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
received was what you intended to type; if the input was such that you
@var{know} it should have been processed quickly, report a bug.  If you
don't know whether the command should take a long time, find out by looking
in the manual or by asking for assistance.

  If a command you are familiar with causes an Emacs error message in a
case where its usual definition ought to be reasonable, it is probably a
bug.

  If a command does the wrong thing, that is a bug.  But be sure you know
for certain what it ought to have done.  If you aren't familiar with the
command, or don't know for certain how the command is supposed to work,
then it might actually be working right.  Rather than jumping to
conclusions, show the problem to someone who knows for certain.

  Finally, a command's intended definition may not be best for editing
with.  This is a very important sort of problem, but it is also a matter of
judgment.  Also, it is easy to come to such a conclusion out of ignorance
of some of the existing features.  It is probably best not to complain
about such a problem until you have checked the documentation in the usual
ways, feel confident that you understand it, and know for certain that what
you want is not available.  If you are not sure what the command is
supposed to do after a careful reading of the manual, check the index and
glossary for any terms that may be unclear.  If you still do not
understand, this indicates a bug in the manual.  The manual's job is to
make everything clear.  It is just as important to report documentation
bugs as program bugs.

  If the online documentation string of a function or variable disagrees
with the manual, one of them must be wrong, so report the bug.

@subsection How to Report a Bug

@findex emacs-version
  When you decide that there is a bug, it is important to report it and to
report it in a way which is useful.  What is most useful is an exact
description of what commands you type, starting with the shell command to
run Emacs, until the problem happens.  Always include the version number
of Emacs that you are using; type @kbd{M-x emacs-version} to print this.

  The most important principle in reporting a bug is to report @var{facts},
not hypotheses or categorizations.  It is always easier to report the facts,
but people seem to prefer to strain to posit explanations and report
them instead.  If the explanations are based on guesses about how Emacs is
implemented, they will be useless; we will have to try to figure out what
the facts must have been to lead to such speculations.  Sometimes this is
impossible.  But in any case, it is unnecessary work for us.

  For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
@key{RET}}, visiting a file which (you know) happens to be rather large,
and Emacs prints out @samp{I feel pretty today}.  The best way to report
the bug is with a sentence like the preceding one, because it gives all the
facts and nothing but the facts.

  Do not assume that the problem is due to the size of the file and say,
``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
This is what we mean by ``guessing explanations''.  The problem is just as
likely to be due to the fact that there is a @samp{z} in the file name.  If
this is so, then when we got your report, we would try out the problem with
some ``large file'', probably with no @samp{z} in its name, and not find
anything wrong.  There is no way in the world that we could guess that we
should try visiting a file with a @samp{z} in its name.

  Alternatively, the problem might be due to the fact that the file starts
with exactly 25 spaces.  For this reason, you should make sure that you
inform us of the exact contents of any file that is needed to reproduce the
bug.  What if the problem only occurs when you have typed the @kbd{C-x a l}
command previously?  This is why we ask you to give the exact sequence of
characters you typed since starting to use Emacs.

  You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
you @i{know} that it makes no difference which visiting command is used.
Similarly, rather than saying ``if I have three characters on the line,''
say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
the way you entered the text.@refill

  If you are not in Fundamental mode when the problem occurs, you should
say what mode you are in.

  If the manifestation of the bug is an Emacs error message, it is
important to report not just the text of the error message but a backtrace
showing how the Lisp program in Emacs arrived at the error.  To make the
backtrace, you must execute the Lisp expression
@code{(setq @w{debug-on-error t})} before the error happens (that is to
say, you must execute that expression and then make the bug happen).  This
causes the Lisp debugger to run (@pxref{Lisp Debug}).  The debugger's
backtrace can be copied as text into the bug report.  This use of the
debugger is possible only if you know how to make the bug happen again.  Do
note the error message the first time the bug happens, so if you can't make
it happen again, you can report at least that.

  Check whether any programs you have loaded into the Lisp world, including
your init file, set any variables that may affect the functioning of
Emacs.  @xref{Init File}.  Also, see whether the problem happens in a
freshly started Emacs without loading your init file (start Emacs with
the @code{-q} switch to prevent loading the init file).  If the problem
does @var{not} occur then, it is essential that we know the contents of
any programs that you must load into the Lisp world in order to cause
the problem to occur.

  If the problem does depend on an init file or other Lisp programs that
are not part of the standard Emacs system, then you should make sure it is
not a bug in those programs by complaining to their maintainers first.
After they verify that they are using Emacs in a way that is supposed to
work, they should report the bug.

  If you can tell us a way to cause the problem without visiting any files,
please do so.  This makes it much easier to debug.  If you do need files,
make sure you arrange for us to see their exact contents.  For example, it
can often matter whether there are spaces at the ends of lines, or a
newline after the last line in the buffer (nothing ought to care whether
the last line is terminated, but tell that to the bugs).

@findex open-dribble-file
@cindex dribble file
  The easy way to record the input to Emacs precisely is to write a
dribble file; execute the Lisp expression:

@example
(open-dribble-file "~/dribble")
@end example

@noindent
using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
Emacs.  From then on, all Emacs input will be written in the specified
dribble file until the Emacs process is killed.

@findex open-termscript
@cindex termscript file
  For possible display bugs, it is important to report the terminal type
(the value of environment variable @code{TERM}), the complete termcap entry
for the terminal from @file{/etc/termcap} (since that file is not identical
on all machines), and the output that Emacs actually sent to the terminal.
The way to collect this output is to execute the Lisp expression:

@example
(open-termscript "~/termscript")
@end example

@noindent using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer
just after starting Emacs.  From then on, all output from Emacs to the
terminal will be written in the specified termscript file as well, until
the Emacs process is killed.  If the problem happens when Emacs starts
up, put this expression into your init file so that the termscript file
will be open when Emacs displays the screen for the first time.
@xref{Init File}. Be warned: it is often difficult, and sometimes
impossible, to fix a terminal-dependent bug without access to a terminal
of the type that stimulates the bug.@refill

The newsgroup @samp{comp.emacs.xemacs} may be used for bug reports,
other discussions and requests for assistance.

If you don't have access to this newgroup, you can subscribe to the
mailing list version: the newsgroup is bidirectionally gatewayed into
the mailing list @samp{xemacs@@xemacs.org}.

To be added or removed from this mailing list, send mail to
@samp{xemacs-request@@xemacs.org}.  Do not send requests for addition
to the mailing list itself.

The mailing lists and newsgroups are archived on our anonymous FTP server,
@samp{ftp.xemacs.org}, and at various other archive sites around the net. You
should also check the @samp{FAQ} in @samp{/pub/xemacs} on our anonymous
FTP server. It provides some introductory information and help for initial
configuration problems.

repo_name: mthl/texinfo

license: mit


code:
@node Undo, Minibuffer, Basic, Top
@chapter Undoing Changes
@cindex undo
@cindex mistakes, correcting

  Emacs allows you to undo all changes you make to the text of a buffer,
up to a certain amount of change (8000 characters).  Each buffer records
changes individually, and the undo command always applies to the
current buffer.  Usually each editing command makes a separate entry
in the undo records, but some commands such as @code{query-replace}
make many entries, and very simple commands such as self-inserting
characters are often grouped to make undoing less tedious.

@table @kbd
@item C-x u
Undo one batch of changes (usually, one command's worth) (@code{undo}).
@item C-_
The same.
@end table

@kindex C-x u
@kindex C-_
@findex undo
  The command @kbd{C-x u} or @kbd{C-_} allows you to undo changes.  The
first time you give this command, it undoes the last change.  Point
moves to the text affected by the undo, so you can see what was undone.

  Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo
earlier and earlier changes, back to the limit of what has been
recorded.  If all recorded changes have already been undone, the undo
command prints an error message and does nothing.

  Any command other than an undo command breaks the sequence of undo
commands.  Starting at this moment, the previous undo commands are
considered ordinary changes that can themselves be undone.  Thus, you can
redo changes you have undone by typing @kbd{C-f} or any other command
that have no important effect, and then using more undo commands.

  If you notice that a buffer has been modified accidentally, the
easiest way to recover is to type @kbd{C-_} repeatedly until the stars
disappear from the front of the mode line.  When that happens, all the
modifications you made have been canceled.  If you do not remember
whether you changed the buffer deliberately, type @kbd{C-_} once. When
you see Emacs undo the last change you made, you probably remember why you
made it.  If the change was an accident, leave it undone.  If it was
deliberate, redo the change as described in the preceding paragraph.

  Whenever an undo command makes the stars disappear from the mode line,
the buffer contents is the same as it was when the file was last read in
or saved.

  Not all buffers record undo information.  Buffers whose names start with
spaces don't; these buffers are used internally by Emacs and its extensions
to hold text that users don't normally look at or edit.  Minibuffers,
help buffers, and documentation buffers also don't record undo information.

  Emacs can remember at most 8000 or so characters of deleted or
modified text in any one buffer for reinsertion by the undo command.
There is also a limit on the number of individual insert, delete, or
change actions that Emacs can remember.

  There are two keys to run the @code{undo} command, @kbd{C-x u} and
@kbd{C-_}, because on some keyboards, it is not obvious how to type
@kbd{C-_}. @kbd{C-x u} is an alternative you can type in the same
fashion on any terminal.


code:
@node Windows, Mule, Buffers, Top
@chapter Multiple Windows
@cindex windows

  Emacs can split the frame into two or many windows, which can display
parts of different buffers or different parts of one buffer.  If you are
running XEmacs under X, that means you can have the X window that contains
the Emacs frame have multiple subwindows.

@menu
* Basic Window::     Introduction to Emacs windows.
* Split Window::     New windows are made by splitting existing windows.
* Other Window::     Moving to another window or doing something to it.
* Pop Up Window::    Finding a file or buffer in another window.
* Change Window::    Deleting windows and changing their sizes.
@end menu

@node Basic Window, Split Window, Windows, Windows
@section Concepts of Emacs Windows

  When Emacs displays multiple windows, each window has one Emacs
buffer designated for display.  The same buffer may appear in more
than one window; if it does, any changes in its text are displayed in all
the windows that display it.  Windows showing the same buffer can
show different parts of it, because each window has its own value of point.

@cindex selected window
  At any time, one  window is the @dfn{selected window}; the buffer
 displayed by that window is the current buffer.  The cursor
shows the location of point in that window.  Each other window has a
location of point as well, but since the terminal has only one cursor, it
cannot show the location of point in the other windows.

  Commands to move point affect the value of point for the selected Emacs
window only.  They do not change the value of point in any other Emacs
window, including those showing the same buffer.  The same is true for commands
such as @kbd{C-x b} to change the selected buffer in the selected window;
they do not affect other windows at all.  However, there are other commands
such as @kbd{C-x 4 b} that select a different window and switch buffers in
it.  Also, all commands that display information in a window, including
(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
(@code{list-buffers}), work by switching buffers in a non-selected window
without affecting the selected window.

  Each window has its own mode line, which displays the buffer name,
modification status, and major and minor modes of the buffer that is
displayed in the window.  @xref{Mode Line}, for details on the mode
line.

@node Split Window, Other Window, Basic Window, Windows
@section Splitting Windows

@table @kbd
@item C-x 2
Split the selected window into two windows, one above the other
(@code{split-window-vertically}).
@item C-x 3
Split the selected window into two windows positioned side by side
(@code{split-window-horizontally}).
@item C-x 6
Save the current window configuration in register @var{reg} (a letter).
@item C-x 7
Restore (make current) the window configuration in register
@var{reg} (a letter).  Use with a register previously set with @kbd{C-x 6}.
@end table

@kindex C-x 2
@findex split-window-vertically
  The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
selected window into two windows, one above the other.  Both windows
start out displaying the same buffer, with the same value of point.  By
default each of the two windows gets half the height of the window that
was split.  A numeric argument specifies how many lines to give to the
top window.

@kindex C-x 3
@findex split-window-horizontally
  @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected
window into two side-by-side windows.  A numeric argument specifies how
many columns to give the one on the left.  A line of vertical bars
separates the two windows.  Windows that are not the full width of the
frame have truncated mode lines which do not always appear in inverse
video, because Emacs display routines cannot display a region of inverse
video that is only part of a line on the screen.

@vindex truncate-partial-width-windows
  When a window is less than the full width, many text lines are too
long to fit.  Continuing all those lines might be confusing.  Set the
variable @code{truncate-partial-width-windows} to non-@code{nil} to
force truncation in all windows less than the full width of the frame,
independent of the buffer and its value for @code{truncate-lines}.
@xref{Continuation Lines}.@refill

  Horizontal scrolling is often used in side-by-side windows.
@xref{Display}.

@findex jump-to-register
@findex window-configuration-to-register
You can resize a window and store that configuration in a register by
supplying a @var{register} argument to @code{window-configuration-to-register}
(@kbd{C-x 6}). To return to the window configuration established with
@code{window-configuration-to-register}, use @code{jump-to-register}
(@kbd{C-x j}).

@node Other Window, Pop Up Window, Split Window, Windows
@section Using Other Windows

@table @kbd
@item C-x o
Select another window (@code{other-window}).  That is the letter `o', not zero.
@item M-C-v
Scroll the next window (@code{scroll-other-window}).
@item M-x compare-windows
Find the next place where the text in the selected window does not match
the text in the next window.
@item M-x other-window-any-frame @var{n}
Select the @var{n}th different window on any frame.
@end table

@kindex C-x o
@findex other-window
  To select a different window, use @kbd{C-x o} (@code{other-window}).
That is an `o', for `other', not a zero.  When there are more than
two windows, the command moves through all the windows in a cyclic
order, generally top to bottom and left to right.  From the rightmost
and bottommost window, it goes back to the one at the upper left corner.
A numeric argument, @var{n}, moves several steps in the cyclic order of
windows. A negative numeric argument moves around the cycle in the
opposite order.  If the optional second argument @var{which-frames} is
non-@code{nil}, the function cycles through all frames.  When the
minibuffer is active, the minibuffer is the last window in the cycle;
you can switch from the minibuffer window to one of the other windows,
and later switch back and finish supplying the minibuffer argument that
is requested.  @xref{Minibuffer Edit}.

@findex other-window-any-frame
 The command @kbd{M-x other-window-any-frame} also selects the window
@var{n} steps away in the cyclic order.  However, unlike @code{other-window},
this command selects a window on the next or previous frame instead of
wrapping around to the top or bottom of the current frame, when there
are no more windows.

@kindex C-M-v
@findex scroll-other-window
  The usual scrolling commands (@pxref{Display}) apply to the selected
window only.  @kbd{M-C-v} (@code{scroll-other-window}) scrolls the
window that @kbd{C-x o} would select.  Like @kbd{C-v}, it takes positive
and negative arguments.

@findex compare-windows
  The command @kbd{M-x compare-windows} compares the text in the current
window with the text in the next window.  Comparison starts at point in each
window.  Point moves forward in each window, a character at a time,
until the next set of characters in the two windows are different.  Then the
command is finished.

A prefix argument @var{ignore-whitespace} means ignore changes in
whitespace.  The variable @code{compare-windows-whitespace} controls how
whitespace is skipped.

If @code{compare-ignore-case} is non-@code{nil}, changes in case are
also ignored.

@node Pop Up Window, Change Window, Other Window, Windows
@section Displaying in Another Window

@kindex C-x 4
  @kbd{C-x 4} is a prefix key for commands that select another window
(splitting the window if there is only one) and select a buffer in that
window.  Different @kbd{C-x 4} commands have different ways of finding the
buffer to select.

@findex switch-to-buffer-other-window
@findex find-file-other-window
@findex find-tag-other-window
@findex dired-other-window
@findex mail-other-window
@table @kbd
@item C-x 4 b @var{bufname} @key{RET}
Select buffer @var{bufname} in another window.  This runs
@code{switch-to-buffer-other-window}.
@item C-x 4 f @var{filename} @key{RET}
Visit file @var{filename} and select its buffer in another window.  This
runs @code{find-file-other-window}.  @xref{Visiting}.
@item C-x 4 d @var{directory} @key{RET}
Select a Dired buffer for directory @var{directory} in another window.
This runs @code{dired-other-window}.  @xref{Dired}.
@item C-x 4 m
Start composing a mail message in another window.  This runs
@code{mail-other-window}, and its same-window version is @kbd{C-x m}
(@pxref{Sending Mail}).
@item C-x 4 .
Find a tag in the current tag table in another window.  This runs
@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
(@pxref{Tags}).
@end table

@vindex display-buffer-function
If the variable @code{display-buffer-function} is non-@code{nil}, its value is
the function to call to handle @code{display-buffer}. It receives two
arguments, the buffer and a flag that if non-@code{nil} means that the
currently selected window is not acceptable. Commands such as
@code{switch-to-buffer-other-window} and @code{find-file-other-window}
work using this function.

@node Change Window,, Pop Up Window, Windows
@section Deleting and Rearranging Windows

@table @kbd
@item C-x 0
Get rid of the selected window (@code{delete-window}).  That is a zero.
If there is more than one Emacs frame, deleting the sole remaining
window on that frame deletes the frame as well. If the current frame
is the only frame, it is not deleted.
@item C-x 1
Get rid of all windows except the selected one
(@code{delete-other-windows}).
@item C-x ^
Make the selected window taller, at the expense of the other(s)
@*(@code{enlarge-window}).
@item C-x @}
Make the selected window wider (@code{enlarge-window-horizontally}).
@end table

@kindex C-x 0
@findex delete-window
  To delete a window, type @kbd{C-x 0} (@code{delete-window}).  (That is a
zero.)  The space occupied by the deleted window is distributed among the
other active windows (but not the minibuffer window, even if that is active
at the time).  Once a window is deleted, its attributes are forgotten;
there is no automatic way to make another window of the same shape or
showing the same buffer.  The buffer continues to exist, and you can
select it in any window with @kbd{C-x b}.

@kindex C-x 1
@findex delete-other-windows
  @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0};
it deletes all the windows except the selected one (and the minibuffer).
The selected window expands to use the whole frame except for the echo
area.

@kindex C-x ^
@findex enlarge-window
@kindex C-x @}
@findex enlarge-window-horizontally
@vindex window-min-height
@vindex window-min-width
  To readjust the division of space among existing windows, use @kbd{C-x
^} (@code{enlarge-window}).  It makes the currently selected window
longer by one line or as many lines as a numeric argument specifies.
With a negative argument, it makes the selected window smaller.
@kbd{C-x @}} (@code{enlarge-window-horizontally}) makes the selected
window wider by the specified number of columns.  The extra screen space
given to a window comes from one of its neighbors, if that is possible;
otherwise, all the competing windows are shrunk in the same proportion.
If this makes some windows too small, those windows are deleted and their
space is divided up.   Minimum window size is specified by the variables
@code{window-min-height} and @code{window-min-width}.

You can also resize windows within a frame by clicking the left mouse
button on a modeline, and dragging.

Clicking the right button on a mode line pops up a menu of common window
manager operations.  This menu contains the following options:

@cindex Windows menu
@cindex Pull-down Menus
@cindex menus
@table @b
@item Delete Window
Remove the window above this modeline from the frame.

@item Delete Other Windows
Delete all windows on the frame except for the one above this modeline.

@item Split Window
Split the window above the mode line in half, creating another window.

@item Split Window Horizontally
Split the window above the mode line in half horizontally, so that there
will be two windows side-by-side.

@item Balance Windows
Readjust the sizes of all windows on the frame until all windows have
roughly the same number of lines.
@end table