% JOVE Users manual, to be included by "jove.ltx".

\RCS $Id: joveman.tex,v 14.30 1993/02/09 23:08:24 tom Exp tom $

\title{JOVE Users Manual}
\author{
Jonathan Payne \\
(revised for 4.3BSD by Doug Kingston and Mark Seiden) \\
(revised for 7th Ed., HP-UX, VMS, Atari ST and MS-DOS by Tom Hageman)
}
\date{February 1993}
\maketitle\bigskip

\section{Introduction}

\Jove{}\nroff{*}\footnote{
\nroff{*}
\jove{} stands for Jonathan's Own Version of Emacs.
}
is an advanced, self-documenting, customizable real-time display editor.
It (and this tutorial introduction) are based on the original
{\sc\lowercase{EMACS}} editor and user manual written at M.I.T.\ by Richard
Stallman\nroff{\(dg.}\footnote{
\nroff{\(dg}
Although \jove{} is meant to be compatible with {\sc\lowercase{EMACS}}, and indeed
many of the basic commands are very similar, there are some major
differences between the two editors, and you should not rely on their
behaving identically.
}.
\par\noindent
\Jove{} is considered a \Def{display} editor because normally the text
being edited is visible on the screen and is updated automatically as
you type your commands.
\par\noindent
It's considered a \Def{real-time} editor because the display is updated
very frequently, usually after each character or pair of characters you
type.  This minimizes the amount of information you must keep in your
head as you edit.
\par\noindent
\Jove{} is \Def{advanced} because it provides facilities that go beyond
simple insertion and deletion:  filling of text; automatic indentations
of programs; view more than one file at once; and dealing in terms of
characters, words, lines, sentences and paragraphs.  It is much easier
to type one command meaning ``go to the end of the paragraph'' than to
find the desired spot with repetition of simpler commands.
\par\noindent
\Def{Self-documenting} means that at almost any time you can easily find
out what a command does, or to find all the commands that pertain to a
topic.
\par\noindent
\Def{Customizable} means that you can change the definition of \jove{}
commands in little ways.  For example, you can rearrange the command
set; if you prefer to use arrow keys for the four basic cursor motion
commands (up, down, left and right), you can.  Another sort of
customization is writing new commands by combining built in commands.

\section{The Organization of the Screen}

\Jove{} divides the screen up into several sections.  The biggest of
these sections is used to display the text you are editing.  The
terminal's cursor shows the position of \Def{point}, the location at
which editing takes place.  While the cursor appears to point {\em at\/}
a character, point should be thought of as between characters; it points
{\em before\/} the character that the cursor appears on top of.
Terminals have only one cursor, and when output is in progress it must
appear where the typing is being done.  This doesn't mean that point is
moving; it is only that \jove{} has no way of showing you the location
of point except when the terminal is idle.
\par\noindent
The lines of the screen are usually available for displaying text but
sometimes are pre-empted by typeout from certain commands (such as a
listing of all the editor commands).  Most of the time, output from
commands like these is only desired for a short period of time, usually
just long enough to glance at it.  When you have finished looking at the
output, you can type \key{Space} or \key{Return} to make your text
reappear.  (Usually a \key{Space} or \key{Return} that you type inserts
itself, but when there is typeout on the screen, it does nothing but get
rid of that).  Any other command executes normally, {\em after\/}
redrawing your text.

\subsection{The Message Line}

The bottom line on the screen, called the \Def{message line}, is
reserved for printing messages and for accepting input from the user,
such as filenames or search strings.  When \jove{} prompts for input,
the cursor will temporarily appear on the bottom line, waiting for you
to type a string.  When you have finished typing your input, you can
type a \key{Return} to send it to \jove{}. If you change your mind about
running the command that is waiting for input, you can type \key{Control-G}
to abort, and you can continue with your editing.
\par\noindent
When \jove{} is prompting for a filename, all the usual editing
facilities can be used to fix typos and such; in addition, \jove{} has
the following extra functions:
\begin{description}
\item[{\carat{}N}]
Insert the next filename from the argument list.
\item[{\carat{}P}]
Insert the previous filename from the argument list.
\item[{\carat{}R}]
Insert the full pathname of the file in the current buffer.
\end{description}
Sometimes you will see \out{-\,-more-\,-} on the message line.  This happens
when typeout from a command is too long to fit in the screen.  It means
that if you type a \key{Space} the next screenful of typeout will be
printed. Typing a \key{Return} just scrolls the typeout a single line.
Typing \key{C-G} or \key{Rubout} will discard the rest of the output.
Typing any other command will discard the rest of the output and also
execute the command.
\par\noindent
The message line and the list of filenames from the shell command that
invoked \jove{} are kept in a special buffer called \Def{*minibuf*} that
can be edited like any other buffer.

\subsection{The Mode Line}

At the bottom of the screen, but above the message line, is the
\Def{mode line}.  The mode line format looks like this:
\begin{trivlist}\vspace*{0.5ex}\item[]
\framebox[\textwidth][l]{\out{~JOVE~~(major~minor)~~~Buffer:~bufr~~"file"~*}}
\end{trivlist}\vspace*{0.5ex}
{\em Major\/} is the name of the current \Def{major mode}.  At any time,
\jove{} can be in only one major mode at a time.  Currently there are
only five major modes: {\bf Fundamental}, {\bf Text}, {\bf Lisp},
{\bf C} and {\bf Perl}.
\par\noindent
{\em Minor\/} is a list of the \Def{minor modes} that are turned on.
{\bf Abbrev} means that \Def{Word Abbrev} mode is on; {\bf AI} means
that \Def{Auto Indent} mode is on; {\bf Fill} means that \Def{Auto Fill}
mode is on; {\bf OvrWt} means that \Def{Over Write} mode is on;
{\bf Match} means that \Def{Show Match} mode is on; {\bf View} means that
\Def{View} (read-only) mode is on.  {\bf Def} means that you are in the
process of defining a keyboard macro.  This is not really a mode, but
it's useful to be reminded about it.  The meanings of these modes are
described later in this document.
\par\noindent
{\em Bufr\/} is the name of the currently selected \Def{buffer}.  Each
buffer has its own name and holds a file being edited; this is how
\jove{} can hold several files at once.  But at any given time you are
editing only one of them, the \Def{selected} buffer.  When we speak of
what some command does to ``the buffer'', we are talking about the
currently selected buffer.  Multiple buffers makes it easy to switch
around between several files, and then it is very useful that the mode
line tells you which one you are editing at any time.  (You will see
later that it is possible to divide the screen into multiple
\Def{windows}, each showing a different buffer.  If you do this, there
is a mode line beneath each window.)
\par\noindent
{\em File\/} is the name of the file that you are editing.  This is the
default filename for commands that expect a filename as input.
\par\noindent
The asterisk at the end of the mode line means that there are changes in
the buffer that have not been saved in the file.  If the file has not
been changed since it was read in or saved, there is no asterisk.

\section{Command Input Conventions}

\subsection{Notational Conventions for ASCII Characters}

In this manual, \Def{Control} characters (that is, characters that are
typed with the \key{Control} key and some other key at the same time)
are represented by \key{C-} followed by another character.  Thus,
\key{C-A} is the character you get when you type \key{A} with the
\key{Control} key (sometimes labeled \key{CTRL}) down.  Most control
characters when present in the \jove{} buffer are displayed with a
caret; thus, \key{\carat{}A} for \key{C-A}.  \key{Rubout} (or
\key{DEL}) is displayed as \key{\carat{}?}, and \key{Escape} as
\key{\carat{}[}.  Function keys (like the Arrow keys) are represented
in \jove{} by the four-character sequence \key{\carat{}:xy} where \key{xy}
is the key's mnemonic as defined by \file{termcap\,(5)}\nroff{*.}\footnote{
\nroff{*}
This is the representation that \jove{} uses, e.g., to show the name of
the key in a \cmd{describe-key} command, or that you can use in
your \jove{} startup file to bind something to a function key.
Function keys do not have any special significance in a \jove{} {\em buffer\/}.
In fact their internal representation varies for different terminal
types, so it is debatable that they can even be `present' in a buffer.
}.

\subsection{Command and Filename Completion}

When you are typing the name of a \jove{} command, you need type only
enough letters to make the name unambiguous.  At any point in the course
of typing the name, you can type question mark (\key{?}) to see a list
of all the commands whose names begin with the characters you've already
typed; you can type \key{Space} to have \jove{} supply as many
characters as it can; or you can type \key{Return} to complete the
command if there is only one possibility.  For example, if you have
typed the letters ``{\em au\/}'' and you then type a question mark, you
will see the list
\begin{quote}
auto-execute-command \\
auto-execute-macro \\
auto-fill-mode \\
auto-indent-mode
\end{quote}
If you type a \key{Return} at this point, \jove{} will complain by
ringing the bell, because the letters you've typed do not unambiguously
specify a single command.  But if you type \key{Space}, \jove{} will
supply the characters ``{\em to-\/}'' because all commands that begin
``{\em au\/}'' also begin ``{\em auto-\/}''.  You could then type the
letter ``{\em f\/}'' followed by either \key{Space} or \key{Return}, and
\jove{} would complete the entire command.
\par\noindent
Whenever \jove{} is prompting you for a filename, say in the
\cmd{find-file} command, you also need only type enough of the name to
make it unambiguous with respect to files that already exist.  In this
case, question mark and \key{Space} work just as they do in command
completion, but \key{Return} always accepts the name just as you've
typed it, because you might want to create a new file with a name
similar to that of an existing file.  The variable
\cmd{bad-filename-extensions} contains a list of words separated by
spaces which are to be considered bad filename extensions, and so will
not be counted in filename completion.  The default is \file{.o} so
if you have \file{jove.c} and \file{jove.o} in the same directory, the
filename completion will not complain of an ambiguity because it will
ignore \file{jove.o}.

\section{Commands and Variables}

\Jove{} is composed of \Def{commands} which have long names such as
\cmd{next-line}.  Then \Def{keys} such as \key{C-N} are connected to
commands through the \Def{command dispatch table}.  When we say that
\key{C-N} moves the cursor down a line, we are glossing over a
distinction which is unimportant for ordinary use, but essential for
simple customization:  it is the command \cmd{next-line} which knows how
to move a down line, and \key{C-N} moves down a line because it is
connected to that command.  The name for this connection is a
\Def{binding}; we say that the key \key{C-N} {\em is bound to\/} the
command \cmd{next-line}.
\par\noindent
Not all commands are bound to keys.  To invoke a command that isn't
bound to a key, you can type the sequence \key{ESC~X}, which is bound to
the command \cmd{execute-named-command}.  You will then be able to type
the name of whatever command you want to execute on the message line.
\par\noindent
Sometimes the description of a command will say ``to change this, set
the variable \cmd{mumble-foo}''.  A variable is a name used to remember
a value.
\Jove{} contains variables which are there so that you can change
them if you want to customize.  The variable's value is examined by some
command, and changing that value makes the command behave differently.
Until you are interesting in customizing \jove{} you can ignore this
information.

\subsection{Prefix Characters}

Because there are more command names than keys, \jove{} provides
\Def{prefix characters} to increase the number of commands that can be
invoked quickly and easily.  When you type a prefix character \jove{}
will wait for another character before deciding what to do.  If you wait
more than a second or so, \jove{} will print the prefix character on the
message line as a reminder and leave the cursor down there until you
type your next character.  There are two prefix characters built into
\jove{}: \key{Escape} and \key{Control-X}.  How the next character is
interpreted depends on which prefix character you typed.  For example,
if you type \key{Escape} followed by \key{B} you'll run
\cmd{backward-word}, but if you type \key{Control-X} followed by \key{B}
you'll run \cmd{select-buffer}.  Elsewhere in this manual, the
\key{Escape} key is indicated as \key{ESC}, which is also what \jove{}
displays on the message line for \key{Escape}.

\subsection{Help}

To get a list of keys and their associated commands, you type
\key{ESC~X} \cmd{describe-bindings}.  If you want to describe a single
key, \key{C-X~?} (\cmd{describe-key}) will work.  A more verbose
description of an individual command is available by using \key{ESC~?}
(\cmd{describe-command}) or ---more directly--- by \key{C-U~C-X~?}, and
descriptions of variables by using \key{C-X~H}
(\cmd{describe-variable}).  If you can't remember the name of the thing
you want to know about, \key{ESC~H} (\cmd{apropos}) will tell you if a
command or variable has a given string in its name.  For example,
\key{ESC~H describe} will list the names of the four describe commands
mentioned briefly in this section.

\section{Basic Editing Commands}

\subsection{Inserting Text}

To insert printing characters into the text you are editing, just type
them.  All printing characters you type are inserted into the text at
the cursor (that is, at \Def{point}), and the cursor moves forward.  Any
characters after the cursor move forward too.  If the text in the buffer
is \eg{FOOBAR}, with the cursor before the \eg{B}, then if you type
\key{XX}, you get \eg{FOOXXBAR}, with the cursor still before the \eg{B}.
\par\noindent
To correct text you have just inserted, you can use \key{Rubout}\nroff{*.}\footnote{
\nroff{*}
In the original distribution of \jove{} \key{Rubout} is a synonym for
the \key{Delete} key.  Some people prefer that \key{Delete} means
``delete-next'' and \key{Backspace} means ``delete-previous'';
\Jove{} can be installed either way.  These people should read
\key{Rubout} to mean \key{Backspace}.
}.
\key{Rubout} deletes the character {\em before\/} the cursor (not the
one that the cursor is on top of or under; that is the character
{\em after\/} the cursor).  The cursor and all characters after it move
backwards.  Therefore, if you typing a printing character and then type
\key{Rubout}, they cancel out.
\par\noindent
To end a line and start typing a new one, type \key{Return}.
\key{Return} operates by inserting a \Def{line-separator}, so if you
type \key{Return} in the middle of a line, you break the line in two.
Because a line-separator is just a single character, you can type
\key{Rubout} at the beginning of a line to delete the line-separator and
join it with the preceding line.
\par\noindent
As a special case, if you type \key{Return} at the end of a line and
there are two or more empty lines just below it, \jove{} does not insert
a line-separator but instead merely moves to the next (empty) line.
This behavior is convenient when you want to add several lines of text
in the middle of a buffer.  You can use the \key{Control-O}
(\cmd{newline-and-backup}) command to ``open'' several empty lines at
once; then you can insert the new text, filling up these empty lines.
The advantage is that \jove{} does not have to redraw the bottom part of
the screen for each \key{Return} you type, as it would ordinarily.  That
``redisplay'' can be both slow and distracting.
\par\noindent
If you add too many characters to one line, without breaking it with
\key{Return}, the line will grow too long to display on one screen line.
When this happens, \jove{} puts an \out{!} at the extreme right margin,
and doesn't bother to display the rest of the line unless the cursor
happens to be in it.  The \out{!} is not part of your text; conversely,
even though you can't see the rest of your line, it's still there, and
if you break the line, the \out{!} will go away.
\par\noindent
Direct insertion works for printing characters and space, but other
characters act as editing commands and do not insert themselves.  If you
need to insert a control character, \key{Escape}, or \key{Rubout}, you
must first \Def{quote} it by typing the \key{Control-Q} command first.

\subsection{Moving the Cursor}

To do more than insert characters, you have to know how to
move the cursor.  Here are a few of the commands for doing that.
\begin{description}
\item[{C-A}]
Move to the beginning of the line.
\item[{C-E}]
Move to the end of the line.
\item[{C-F}]
Move forward over one character.\nroff{*}\footnote{
\nroff{*}
On many terminals you can also use the Arrow keys.
}
\item[{C-B}]
Move backward over one character.
\item[{C-N}]
Move down one line,
vertically.
If you start in the middle of one line,
you end in the middle of the next.
\item[{C-P}]
Move up one line,
vertically.
\item[{ESC~$<$}]
Move to the beginning of the entire buffer.
\item[{ESC~$>$}]
Move to the end of the entire buffer.
\item[{ESC~,}]
Move to the beginning of the visible window.
\item[{ESC~.}]
Move to the end of the visible window.
\end{description}

\subsection{Erasing Text}

\begin{description}
\item[{Rubout}]
Delete the character before the cursor.
\item[{C-D}]
Delete the character after the cursor.
\item[{C-K}]
Kill to the end of the line.
\end{description}
You already know about the \key{Rubout} command which deletes the
character before the cursor.  Another command, \key{Control-D}, deletes
the character after the cursor, causing the rest of the text on the line
to shift left.  If \key{Control-D} is typed at the end of a line, that
line and the next line are joined together.
\par\noindent
To erase a larger amount of text, use the \key{Control-K} command, which
kills a line at a time.  If \key{Control-K} is done at the beginning or
middle of a line, it kills all the text up to the end of the line.  If
\key{Control-K} is done at the end of a line, it joins that line and the
next line.  If \key{Control-K} is done twice, it kills the rest of the
line and the line separator also.

\subsection{Files --- Saving Your Work}

The commands above are sufficient for creating text in the \jove{}
buffer.  The more advanced \jove{} commands just make things easier.
But to keep any text permanently you must put it in a \Def{file}.  Files
are the objects which \UNIX{}\nroff{\(dg}\footnote{
\nroff{\(dg}
\UNIX{} is a trademark of Bell Laboratories.
} (and other systems)
use for storing data for a length of time.  To tell
\jove{} to read text into a file, choose a filename, such as
\file{foo.bar}, and type \key{C-X~C-R foo.bar $<$return$>$}.  This reads
the file \file{foo.bar} so that its contents appear on the screen for
editing.  You can make changes, and then save the file by typing
\key{C-X~C-S} ({\it save-file}).  This makes the changes permanent and
actually changes the file \file{foo.bar}.  Until then, the changes are
only inside \jove{} and the file \file{foo.bar} is not really changed.
If the file \file{foo.bar} doesn't exist, and you want to create it,
read it as if it did exist.  When you save your text with \key{C-X~C-S}
the file will be created.

\subsection{Exiting and Pausing --- Leaving \jove{}}

The command \key{C-X~C-C} (\cmd{exit-jove}) will terminate the \jove{}
session and return to the shell.  If there are modified but unsaved
buffers, \jove{} will ask you for confirmation, and you can abort the
command, look at what buffers are modified but unsaved using
\key{C-X~C-B} (\cmd{list-buffers}), save the valuable ones, and then
exit.  Alternatively, you can use \key{ESC~Z} (\cmd{quick-exit}) that
automatically saves all modified buffers before it exits.  If what you
want to do, on the other hand, is \Def{preserve} the editing session but
return to the shell temporarily you can (under Berkeley \UNIX{} only)
issue the command \key{ESC~S} (\cmd{pause-jove}), do your \UNIX{} work
within the c-shell, then return to \jove{} using the \file{fg} command
to resume editing at the point where you paused.  For this sort of
situation you might consider using an \Def{interactive shell} (that is,
a shell in a \jove{} window) which lets you use editor commands to
manipulate your \UNIX{} commands (and their output) while never leaving
the editor.  (The interactive shell feature is described below.)  A
feature that is supported on all \UNIX{} (and most other) systems is \key{ESC~X}
(\cmd{push-shell}), which spawns a shell as a subprocess of \jove{}.

\subsection{Giving Numeric Arguments to \jove{} Commands}

Any \jove{} command can be given a \Def{numeric argument}.
Some commands interpret the argument as a repetition count.  For
example, giving an argument of ten to the \key{C-F} command
(forward-character) moves forward ten characters.  With these commands,
no argument is equivalent to an argument of 1.
\par\noindent
Some commands use the value of the argument, but do something peculiar
(or nothing) when there is no argument.  For example, \key{ESC~G}
(\cmd{goto-line}) with an argument \eg{n} goes to the beginning of the
\eg{n}'th line.  But \key{ESC~G} with no argument asks for the line
number.  Similarly, \key{C-K} with an argument kills that many lines,
including their line separators.  Without an argument, \key{C-K} when
there is text on the line to the right of the cursor kills that text;
when there is no text after the cursor, \key{C-K} deletes the line
separator.
\par\noindent
The fundamental way of specifying an argument is to use \key{ESC}
followed by the digits of the argument, for example, \key{ESC~123~ESC~G}
to go to line 123. Negative arguments are allowed, although not all of
the commands know what to do with one.
\par\noindent
Typing \key{C-U} means do the next command four times.  Two such
\key{C-U}'s multiply the next command by sixteen.  Thus,
\key{C-U~C-U~C-F} moves forward sixteen characters.  This is a good way
to move forward quickly, since it moves about $1/4$th of a line on most
terminals.  Other useful combinations are:
\key{C-U~C-U~C-N} (move down a good fraction of the screen),
\key{C-U~C-U~C-O} (make ``a lot'' of blank lines),
and \key{C-U~C-K} (kill four lines --- note that typing \key{C-K} four times
would kill 2 lines).
\par\noindent
There are other, terminal-dependent ways of specifying arguments.  They
have the same effect but may be easier to type.  If your terminal has a
numeric keypad which sends something recognizably different from the
ordinary digits, it is possible to program \jove{} to to allow use of
the numeric keypad for specifying arguments.

\subsection{The Mark and the Region}

In general, a command that processes an arbitrary part of the buffer
must know where to start and where to stop.  In \jove{} such commands
usually operate on the text between point and \Def{the mark}.  This body
of text is called \Def{the region}.  To specify a region, you set point
to one end of it and mark at the other.  It doesn't matter which one
comes earlier in the text.
\begin{description}
\item[{C-@}]
Set the mark where point is.
\item[{C-X~C-X}]
Interchange mark and point.
\end{description}
For example, if you wish to convert part of the buffer to all
upper-case, you can use the \key{C-X~C-U} command, which operates on the
text in the region.  You can first go to the beginning of the text to be
capitalized, put the mark there, move to the end, and then type
\key{C-X~C-U}.  Or, you can set the mark at the end of the text, move to
the beginning, and then type \key{C-X~C-U} (\cmd{case-region-upper}),
whose name signifies that the region, or everything between point and
mark, is to be capitalized.
\par\noindent
The way to set the mark is with the \key{C-@} (\cmd{set-mark}) command
or (on some terminals) the \key{C-Space} command.  They set the mark
where point is.  Then you can move point away, leaving mark behind.
When the mark is set, \out{[Point pushed]} is printed on the message
line.
\par\noindent
Since terminals have only one cursor, there is no way for \jove{} to
show you where the mark is located.  You have to remember.  The usual
solution to this problem is to set the mark and then use it soon, before
you forget where it is.  But you can see where the mark is with the
command \key{C-X~Space} (\cmd{mark-flash}) which moves the cursor to the
mark for a short while, or with the command \key{C-X~C-X}
(\cmd{exchange-point-and-mark}) which puts the mark where point was and
point where mark was.  The extent of the region is unchanged, but the
cursor and point are now at the previous location of the mark.

\subsection{The Ring of Marks}

Aside from delimiting the region, the mark is also useful for
remembering a spot that you may want to go back to.  To make this
feature more useful, \jove{} remembers 16 previous locations of the
mark.  Most commands that set the mark push the old mark onto this
stack.  To return to a marked location, use \key{C-U~C-@}.  This moves
point to where the mark was, and restores the mark from the stack of
former marks.  So repeated use of this command moves point to all of the
old marks on the stack, one by one.  Since the stack is actually a ring,
enough uses of \key{C-U~C-@} bring point back to where it was
originally.
\par\noindent
Some commands whose primary purpose is to move point a great distance
take advantage of the stack of marks to give you a way to undo the
command.  The best example is \key{ESC~$<$}, which moves to the
beginning of the buffer.  If there are more than 22 lines between the
beginning of the buffer and point, \key{ESC~$<$} sets the mark first, so
that you can use \key{C-U~C-@} or \key{C-X~C-X} to go back to where you
were.  You can change the number of lines from 22 since it is kept in
the variable \cmd{mark-threshold}.  By setting it to 0, you can make
these commands always set the mark.  By setting it to a very large
number you can prevent these commands from ever setting the mark.  If a
command decides to set the mark, it prints the message
\out{[Point~pushed]}.

\subsection{Killing and Moving Text}

The most common way of moving or copying text with \jove{} is to kill
it, and get it back again in one or more places.  This is very safe
because the last several pieces of killed text are all remembered, and
it is versatile, because the many commands for killing syntactic units
can also be used for moving those units.  There are also other ways of
moving text for special purposes.

\subsection{Deletion and Killing}

Most commands which erase text from the buffer save it so that you can
get it back if you change your mind, or move or copy it to other parts
of the buffer.  These commands are known as \Def{kill} commands.  The
rest of the commands that erase text do not save it; they are known as
\Def{delete} commands.  The delete commands include \key{C-D} and
\key{Rubout}, which delete only one character at a time, and those
commands that delete only spaces or line separators.  Commands that can
destroy significant amounts of nontrivial data generally kill.  A
command's name and description will use the words \cmd{kill} or
\cmd{delete} to say which one it does.
\begin{description}
\item[{C-D}]
Delete next character.
\item[{Rubout}]
Delete previous character.
\item[{ESC~\bs}]
Delete spaces and tabs around point.
\item[{C-X~C-O}]
Delete blank lines around the current line.
\item[{C-K}]
Kill rest of line or one or more lines.
\item[{C-W}]
Kill region (from point to the mark).
\item[{ESC~D}]
Kill word.
\item[{ESC~Rubout}]
Kill word backwards.
\item[{ESC~K}]
Kill to end of sentence.
\item[{C-X~Rubout}]
Kill to beginning of sentence.
\end{description}

\subsection{Deletion}

The most basic delete commands are \key{C-D} and \key{Rubout}.
\key{C-D} deletes the character after the cursor, the one the cursor is
``on top of'' or ``underneath''.  The cursor doesn't move.  \key{Rubout}
deletes the character before the cursor, and moves the cursor back.
Line separators act like normal characters when deleted.  Actually,
\key{C-D} and \key{Rubout} aren't always \Def{delete} commands; if you
give an argument, they \Def{kill} instead.  This prevents you from
losing a great deal of text by typing a large argument to a \key{C-D} or
\key{Rubout}.
\par\noindent
The other delete commands are those which delete only formatting
characters:  spaces, tabs, and line separators. \key{ESC~\bs}
(\cmd{delete-white-space}) deletes all the spaces and tab characters
before and after point. \key{C-X~C-O} (\cmd{delete-blank-lines}) deletes
all blank lines after the current line, and if the current line is blank
deletes all the blank lines preceding the current line as well (leaving
one blank line, the current line).

\subsection{Killing by Lines}

The simplest kill command is the \key{C-K} command.  If issued at the
beginning of a line, it kills all the text on the line, leaving it
blank.  If given on a line containing only white space (blanks and tabs)
the line disappears.  As a consequence, if you go to the front of a
non-blank line and type two \key{C-K}'s, the line disappears completely.
\par\noindent
More generally, \key{C-K} kills from point up to the end of the line,
unless it is at the end of a line.  In that case, it kills the line
separator following the line, thus merging the next line into the
current one.  Invisible spaces and tabs at the end of the line are
ignored when deciding which case applies, so if point appears to be at
the end of the line, you can be sure the line separator will be killed.
\par\noindent
\key{C-K} with an argument of zero kills all the text before point on
the current line.

\subsection{Other Kill Commands}

A kill command which is very general is \key{C-W}\nroff{*}\footnote{
\nroff{*}
Often users switch this binding from \key{C-W} to \key{C-X~C-K} because
it is too easy to hit \key{C-W} accidentally.
}
(\cmd{kill-region}), which kills everything between point and the mark.
With this command, you can kill and save contiguous characters, if you
first set the mark at one end of them and go to the other end.
\par\noindent
Other syntactic units can be killed, too; words, with \key{ESC~Rubout}
and \key{ESC~D}; and, sentences, with \key{ESC~K} and \key{C-X~Rubout}.

\subsection{Un-killing}

Un-killing (yanking) is getting back text which was killed.  The usual
way to move or copy text is to kill it and then un-kill it one or more
times.
\begin{description}
\item[{C-Y}]
Yank (re-insert) last killed text.
\item[{ESC~Y}]
Replace re-inserted killed text with the previously killed text.
\item[{ESC~W}]
Save region as last killed text without killing.
\end{description}

Killed text is pushed onto a \Def{ring buffer} called the \Def{kill ring}
that remembers the last 10 blocks of text that were killed.  (Why
it is called a ring buffer will be explained below).  The command
\key{C-Y} (\cmd{yank}) reinserts the text of the most recent kill.  It
leaves the cursor at the end of the text, and puts the mark at the
beginning.  Thus, a single \key{C-Y} undoes the \key{C-W}.
\par\noindent
If you wish to copy a block of text, you might want to use \key{ESC~W}
(\cmd{copy-region}), which copies the region into the kill ring without
removing it from the buffer.  This is approximately equivalent to
\key{C-W} followed by \key{C-Y}, except that \key{ESC~W} does not mark
the buffer as ``changed'' and does not cause the screen to be rewritten.
\par\noindent
There is only one kill ring shared among all the buffers.  After
visiting a new file, whatever was last killed in the previous file is
still on top of the kill ring.  This is important for moving text
between files.

\subsection{Appending Kills}

Normally, each kill command pushes a new block onto the kill ring.
However, two or more kill commands immediately in a row (without any
other intervening commands) combine their text into a single entry on
the ring, so that a single \key{C-Y} command gets it all back as it was
before it was killed.  This means that you don't have to kill all the
text in one command; you can keep killing line after line, or word after
word, until you have killed it all, and you can still get it all back at
once.
\par\noindent
Commands that kill forward from \Def{point} add onto the end of the
previous killed text.  Commands that kill backward from \Def{point} add
onto the beginning.  This way, any sequence of mixed forward and
backward kill commands puts all the killed text into one entry without
needing rearrangement.

\subsection{Un-killing Earlier Kills}

To recover killed text that is no longer the most recent kill, you need
the \key{ESC~Y} (\cmd{yank-pop}) command.  The \key{ESC~Y} command can
be used only after a \key{C-Y} (\cmd{yank}) command or another
\key{ESC~Y}.  It takes the un-killed text inserted by the \key{C-Y} and
replaces it with the text from an earlier kill.  So, to recover the text
of the next-to-the-last kill, you first use \key{C-Y} to recover the
last kill, and then discard it by use of \key{ESC~Y} to move back to the
previous kill.
\par\noindent
You can think of all the last few kills as living on a ring.  After a
\key{C-Y} command, the text at the front of the ring is also present in
the buffer. \key{ESC~Y} ``rotates'' the ring bringing the previous
string of text to the front and this text replaces the other text in the
buffer as well.  Enough \key{ESC~Y} commands can rotate any part of the
ring to the front, so you can get at any killed text so long as it is
recent enough to be still in the ring.  Eventually the ring rotates all
the way around and the most recently killed text comes to the front (and
into the buffer) again. \key{ESC~Y} with a negative argument rotates the
ring backwards.
\par\noindent
When the text you are looking for is brought into the buffer, you can
stop doing \key{ESC~Y}'s and the text will stay there.  It's really just
a copy of what's at the front of the ring, so editing it does not change
what's in the ring.  And the ring, once rotated, stays rotated, so that
doing another \key{C-Y} gets another copy of what you rotated to the
front with \key{ESC~Y}.
\par\noindent
If you change your mind about un-killing, \key{C-W} gets rid of the
un-killed text, even after any number of \key{ESC~Y}'s.

\section{Searching}

The search commands are useful for finding and moving to arbitrary
positions in the buffer in one swift motion.  For example, if you just
ran the spell program on a paper and you want to correct some word, you
can use the search commands to move directly to that word.  There are
two flavors of search: \Def{string search} and \Def{incremental search}.
The former is the default flavor---if you want to use incremental search
you must rearrange the key bindings (see below).

\subsection{Conventional Search}

\begin{description}
\item[{C-S}]
Search forward.
\item[{C-R}]
Search backward.
\end{description}
To search for the string ``\eg{FOO}'' you type
\key{C-S~FOO$<$return$>$}.  If \jove{} finds \eg{FOO} it moves point to
the end of it; otherwise \jove{} prints an error message and leaves
point unchanged. \key{C-S} searches forward from point so only
occurrences of \eg{FOO} after point are found.  To search in the other
direction use \key{C-R}.  It is exactly the same as \key{C-S} except it
searches in the opposite direction, and if it finds the string, it
leaves point at the beginning of it, not at the end as in \key{C-S}.
\par\noindent
While \jove{} is searching it prints the search string on the message
line.  This is so you know what \jove{} is doing.  When the system is
heavily loaded and editing in exceptionally large buffers, searches can
take several (sometimes many) seconds.
\par\noindent
\jove{} remembers the last search string you used, so if you want to
search for the same string you can type \key{C-S~$<$return$>$}.  If you
mistyped the last search string, you can type \key{C-S} followed by
\key{C-R}. \key{C-R}, as usual, inserts the default search string into
the minibuffer, and then you can fix it up.

\subsection{Incremental Search}

This search command is unusual in that is is \Def{incremental}; it
begins to search before you have typed the complete search string.  As
you type in the search string, \jove{} shows you where it would be
found.  When you have typed enough characters to identify the place you
want, you can stop.  Depending on what you will do next, you may or may
not need to terminate the search explicitly with a \key{Return} first.
\par\noindent
The command to search is \key{C-S} (\cmd{i-search-forward}). \key{C-S}
reads in characters and positions the cursor at the first occurrence of
the characters that you have typed so far.  If you type \key{C-S} and
then \key{F}, the cursor moves in the text just after the next
``\eg{F}''.  Type an \key{O}, and see the cursor move to after the next
``\eg{FO}''.  After another \key{O}, the cursor is after the next
``\eg{FOO}''.  At the same time, the \out{FOO} has echoed on the message
line.
\par\noindent
If you type a mistaken character, you can rub it out.  After the
\eg{FOO}, typing a \key{Rubout} makes the ``\eg{O}'' disappear from the
message line, leaving only ``\eg{FO}''.  The cursor moves back in the
buffer to the ``\eg{FO}''.  Rubbing out the ``\eg{O}'' and ``\eg{F}''
moves the cursor back to where you started the search.
\par\noindent
When you are satisfied with the place you have reached, you can type a
\key{Return}, which stops searching, leaving the cursor where the search
brought it.  Also, any command not specially meaningful in searches
stops the searching and is then executed.  Thus, typing \key{C-A} would
exit the search and then move to the beginning of the line.
\key{Return} is necessary only if the next character you want to type is
a printing character, \key{Rubout}, \key{Return}, or another search
command, since those are the characters that have special meanings
inside the search.
\par\noindent
Sometimes you search for ``\eg{FOO}'' and find it, but not the one you
hoped to find.  Perhaps there is a second \eg{FOO} that you forgot
about, after the one you just found.  Then type another \key{C-S} and
the cursor will find the next \eg{FOO}.  This can be done any number of
times.  If you overshoot, you can return to previous finds by rubbing
out the \key{C-S}'s.
\par\noindent
After you exit a search, you can search for the same string again by
typing just \key{C-S~C-S}:  one \key{C-S} command to start the search
and then another \key{C-S} to mean ``search again for the same string''.
\par\noindent
If your string is not found at all, the message line says
\out{Failing I-search}.  The cursor is after the place where \jove{}
found as much of your string as it could.  Thus, if you search for
\eg{FOOT} and there is no \eg{FOOT}, you might see the cursor after the
\eg{FOO} in \eg{FOOL}.  At this point there are several things you can
do.  If your string was mistyped, you can rub some of it out and correct
it.  If you like the place you have found, you can type \key{Return} or
some other \jove{} command to ``accept what the search offered''.  Or
you can type \key{C-G}, which undoes the search altogether and positions
you back where you started the search.
\par\noindent
You can also type \key{C-R} at any time to start searching backwards.
If a search fails because the place you started was too late in the
file, you should do this.  Repeated \key{C-R}'s keep looking backward
for more occurrences of the last search string.  A \key{C-S} starts
going forward again. \key{C-R}'s can be rubbed out just like anything
else.

\subsection{Searching with Regular Expressions}

In addition to the searching facilities described above, \jove{} can
search for patterns using regular expressions.  The handling of regular
expressions in \jove{} is like that of \file{ed\,(1)} or \file{vi\,(1)},
but with some notable additions.  The extra metacharacters understood by
\jove{} are \bs$<$, \bs$>$, \bs$|$ and \bs\{.  The first two of these
match the beginnings and endings of words; Thus the search pattern,
``\eg{\bs$<$Exec}'' would match all words beginning with the letters
``\eg{Exec}''.
\par\noindent
An \bs$|$ signals the beginning of an alternative --- that is, the
pattern ``\eg{foo\bs$|$bar}'' would match either ``\eg{foo}'' or
``\eg{bar}''.  The ``curly brace'' is a way of introducing several
sub-alternatives into a pattern.  It parallels the [$\;$] construct of
regular expressions, except it specifies a list of alternative words
instead of just alternative characters.  So the pattern
``\eg{foo\bs\{bar,baz\bs\Rbrace bie}'' matches ``\eg{foobarbie}'' or
``\eg{foobazbie}''.
\par\noindent
\Jove{} only regards metacharacters as special if the variable
\cmd{match-regular-expressions} is set to ``on''.  The ability to have
\jove{} ignore these characters is useful if you're editing a document
about patterns and regular expressions or when a novice is learning
\jove{}.
\par\noindent
Another variable that affects searching is \cmd{case-ignore-search}.  If
this variable is set to ``on'' then upper case and lower case letters
are considered equal.

\section{Replacement Commands}

Global search-and-replace operations are not needed as often in \jove{}
as they are in other editors, but they are available.  In addition to
the simple Replace operation which is like that found in most editors,
there is a Query Replace operation which asks, for each occurrence of
the pattern, whether to replace it.

\subsection{Global replacement}

To replace every occurrence of \eg{FOO} after point with \eg{BAR}, you
can do, e.g., \key{ESC~R FOO$<$return$>$BAR} as the \cmd{replace-string}
command is bound to the \key{ESC~R}.  Replacement takes place only
between point and the end of the buffer so if you want to cover the
whole buffer you must go to the beginning first.

\subsection{Query Replace}

If you want to change only some of the occurrences of \eg{FOO}, not
all, then the global \cmd{replace-string} is inappropriate; Instead,
use, e.g., \key{ESC~Q FOO$<$return$>$BAR}, to run the command
\cmd{query-replace-string}.  This displays each occurrence of \eg{FOO}
and waits for you to say whether to replace it with a \eg{BAR}.  The
things you can type when you are shown an occurrence of \eg{FOO} are:
\begin{description}
\item[{Space~or~Y}]
to replace the \eg{FOO}.
\item[{Rubout~or~N}]
to skip to the next \eg{FOO} without replacing this one.
\item[{Return~or~Q}]
to stop without doing any more replacements.
\item[{Period}]
to replace this \eg{FOO} and then stop.
\item[{!~or~P}]
to replace all remaining \eg{FOO}'s without asking.
\item[{C-R~or~R}]
to enter a recursive editing level, in case the \eg{FOO} needs to be
edited rather than just replaced with a \eg{BAR}.  When you are done,
exit the recursive editing level with \key{C-X~C-C} and the next
\eg{FOO} will be displayed.
\item[{C-D~or-D}]
to delete the \eg{FOO}.
\item[{C-W~or~W}]
to delete the \eg{FOO}, and then start editing the buffer.  When you
are finished editing whatever is to replace the \eg{FOO}, exit the
recursive editing level with \key{C-X~C-C} and the next \eg{FOO} will
be displayed.
\item[{C-U~or~U}]
move to the last replacement and undo it.
\end{description}
Another alternative is using \key{C-X~R} (\cmd{replace-in-region}) which
is just like \cmd{replace-string} except it searches only within the
region, or even \key{C-X~Q} (\cmd{query-replace-in-region}).
%
% input file: jove.2
%

\section{Commands for English Text}

\Jove{} has many commands that work on the basic units of English text:
words, sentences and paragraphs.

\subsection{Word Commands}

\Jove{} has commands for moving over or operating on words.  By
convention, they are all \key{ESC} commands.
\begin{description}
\item[{ESC~F}]
Move Forward over a word.
\item[{ESC~B}]
Move Backward over a word.
\item[{ESC~D}]
Kill forward to the end of a word.
\item[{ESC~Rubout}]
Kill backward to the beginning of a word.
\end{description}
Notice how these commands form a group that parallels the
character-based commands,
\key{C-F},
\key{C-B},
\key{C-D},
and \key{Rubout}.
\par\noindent
The commands \key{ESC~F} and \key{ESC~B} move forward and backward over
words.  They are thus analogous to \key{Control-F} and \key{Control-B},
which move over single characters.  Like their \key{Control-} analogues,
\key{ESC~F} and \key{ESC~B} move several words if given an argument.
\key{ESC~F} with a negative argument moves backward like \key{ESC~B},
and \key{ESC~B} with a negative argument moves forward.  Forward motion
stops right after the last letter of the word, while backward motion
stops right before the first letter.
\par\noindent
It is easy to kill a word at a time. \key{ESC~D} kills the word after
point.  To be precise, it kills everything from point to the place
\key{ESC~F} would move to.  Thus, if point is in the middle of a word,
only the part after point is killed.  If some punctuation comes after
point, and before the next word, it is killed along with the word.  If
you wish to kill only the next word but not the punctuation, simply do
\key{ESC~F} to get to the end, and kill the word backwards with
\key{ESC~Rubout}. \key{ESC~D} takes arguments just like \key{ESC~F}.
\par\noindent
\key{ESC~Rubout} kills the word before point.  It kills everything from
point back to where \key{ESC~B} would move to.  If point is after the
space in ``\eg{FOO, BAR}'', then ``\eg{FOO, }'' is killed.  If you
wish to kill just ``\eg{FOO}'', then do a \key{ESC~B} and a \key{ESC~D}
instead of a \key{ESC~Rubout}.

\subsection{Sentence Commands}

The \jove{} commands for manipulating sentences and paragraphs are
mostly \key{ESC} commands, so as to resemble the word-handling commands.
\begin{description}
\item[{ESC~A}]
Move back to the beginning of the sentence.
\item[{ESC~E}]
Move forward to the end of the sentence.
\item[{ESC~K}]
Kill forward to the end of the sentence.
\item[{C-X~Rubout}]
Kill back to the beginning of the sentence.
\end{description}
The commands \key{ESC~A} and \key{ESC~E} move to the beginning and end
of the current sentence, respectively.  They were chosen to resemble
\key{Control-A} and \key{Control-E}, which move to the beginning and end
of a line.  Unlike them, \key{ESC~A} and \key{ESC~E} if repeated or
given numeric arguments move over successive sentences.
\Jove{} considers a sentence to end wherever there is a `.', `?', or
`!' followed by the end of a line or by one or more spaces.  Neither
\key{ESC~A} nor \key{ESC~E} moves past the end of the line or spaces
which delimit the sentence.
\par\noindent
Just as \key{C-A} and \key{C-E} have a kill command, \key{C-K}, to go
with them, so \key{ESC~A} and \key{ESC~E} have a corresponding kill
command \key{ESC~K} 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.  Positive arguments serve as a repeat count.
\par\noindent
There is a special command, \key{C-X~Rubout} for killing back to the
beginning of a sentence, because this is useful when you change your
mind in the middle of composing text.

\subsection{Paragraph Commands}

The \jove{} commands for handling paragraphs are
\begin{description}
\item[{ESC~[}]
Move back to previous paragraph beginning.
\item[{ESC~]}]
Move forward to next paragraph end.
\end{description}
\key{ESC~[} moves to the beginning of the current or previous paragraph,
while \key{ESC~]} moves to the end of the current or next paragraph.
Paragraphs are delimited by lines of differing indent, or lines with
text formatter commands, or blank lines.  \Jove{} knows how to deal with
most indented paragraphs correctly, although it can get confused by one-
or two-line paragraphs delimited only by indentation.

\subsection{Text Indentation Commands}

\begin{description}
\item[{Tab}]
Indent ``appropriately'' in a mode-dependent fashion.
\item[{LineFeed}]
Is the same as \key{Return},
except it copies the indent of the line you just left.
\item[{ESC~M}]
Moves to the line's first non-blank character.
\end{description}
The way to request indentation is with the Tab command.  Its precise
effect depends on the major mode.  In \Def{Text} mode, it indents to the
next tab stop.  In \Def{C} mode, it indents to the ``right'' position
for C programs.
\par\noindent
To move over the indentation on a line, do \key{ESC~M}
(\cmd{first-non-blank}).  This command, given anywhere on a line,
positions the cursor at the first non-blank, non-tab character on the
line.

\subsection{Text Filling}

\cmd{Auto Fill} mode causes text to be \Def{filled} (broken up into
lines that fit in a specified width) automatically as you type it in.
If you alter existing text so that it is no longer properly filled,
\jove{} can fill it again if you ask.
\par\noindent
Entering \cmd{Auto Fill} mode is done with \key{ESC~X auto-fill-mode}.
From then on, lines are broken automatically at spaces when they get
longer than the desired width.  To leave \cmd{Auto Fill} mode, once
again execute \key{ESC~X auto-fill-mode}.  When \cmd{Auto Fill} mode is
in effect, the word \out{Fill} appears in the mode line.
\par\noindent
If you edit the middle of a paragraph, it may no longer correctly be
filled.  To refill a paragraph, use the command \key{ESC~J}
(\cmd{fill-paragraph}).  It causes the paragraph that point is inside to
be filled.  All the line breaks are removed and new ones inserted where
necessary.
\par\noindent
The maximum line width for filling is in the variable
\cmd{right-margin}.  Both \key{ESC~J} and auto-fill make sure that no
line exceeds this width.  The value of \cmd{right-margin} is initially
the width of the screen minus 2.
\par\noindent
Normally \key{ESC~J} figures out the indent of the paragraph and uses
that same indent when filling.  If you want to change the indent of a
paragraph you set \cmd{left-margin} to the new position and type
\key{C-U~ESC~J}. \cmd{Fill-paragraph}, when supplied a numeric argument,
uses the value of \cmd{left-margin}.
\par\noindent
If you know where you want to set the right margin but you don't know
the actual value, move to where you want to set the value and use the
\key{C-X~]} (\cmd{right-margin-here}) command. \key{C-X~[}
(\cmd{left-margin-here}) does the same for the \cmd{left-margin}
variable.
\par\noindent
If you want your  text  filled  with  right  margins  aligned,  set  the
variable  \cmd{ragged-right-fill}  to  ``off''.   This  tells \jove{} to
distribute  any  excess  space  evenly  over the line, so that the right
margin looks nice.
% (as you can see---but only in the \TeX{} source text ;-)

\subsection{Case Conversion Commands}

\begin{description}
\item[{ESC~L}]
Convert following word to lower case.
\item[{ESC~U}]
Convert following word to upper case.
\item[{ESC~C}]
Capitalize the following word.
\end{description}
The word conversion commands are most useful. \key{ESC~L}
converts the word after point to lower case, moving past it.  Thus,
successive \key{ESC~L}'s convert successive words. \key{ESC~U} converts
to all capitals instead, while \key{ESC~C} puts the first letter of the
word into upper case and the rest into lower case.  All these 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, because you can move through the test using \key{ESC~L},
\key{ESC~U} or \key{ESC~C} on each word as appropriate.
\par\noindent
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.
\par\noindent
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 the cursor, treating
it as a whole word.
\par\noindent
The other case conversion functions are \cmd{case-region-upper} and
\cmd{case-region-lower}, which convert everything between point and mark
to the specified case.  Point and mark remain unchanged.

\subsection{Commands for Fixing Typos}

In this section we describe the commands that are especially useful for
the times when you catch a mistake on your text after you have made it,
or change your mind while composing text on line.
\begin{description}
\item[{Rubout}]
Delete last character.
\item[{ESC~Rubout}]
Kill last word.
\item[{C-X~Rubout}]
Kill to beginning of sentence.
\item[{C-T}]
Transpose two characters.
\item[{C-X~C-T}]
Transpose two lines.
\item[{ESC~--~ESC~L}]
Convert last word to lower case.
\item[{ESC~--~ESC~U}]
Convert last word to upper case.
\item[{ESC~--~ESC~C}]
Convert last word to lower case with capital initial.
\end{description}

\subsection{Killing Your Mistakes}

The \key{Rubout} command is the most important correction command.
When used among printing (self-inserting) characters,
it can be thought of as canceling the last character typed.
\par\noindent
When your mistake is longer than a couple of characters, it might be
more convenient to use \key{ESC~Rubout} or \key{C-X~Rubout}.
\key{ESC~Rubout} kills back to the start of the last word, and
\key{C-X~Rubout} kills back to the start of the last sentence.
\key{C-X~Rubout} is particularly useful when you are thinking of what to
write as you type it, in case you change your mind about phrasing.
\key{ESC~Rubout} and \key{C-X~Rubout} save the killed text for \key{C-Y}
and \key{ESC~Y} to retrieve.
\par\noindent
\key{ESC~Rubout} is often useful even when you have typed only a few
characters wrong, if you know you are confused in your typing and aren't
sure what you typed.  At such a time, you cannot correct with
\key{Rubout} except by looking at the screen to see what you did.  It
requires less thought to kill the whole word and start over again,
especially if the system is heavily loaded.
\par\noindent
If you were typing a command or command parameters, \key{C-G} will abort
the command with no further processing.

\subsection{Transposition}

The common error of transposing two characters can be fixed with the
\key{C-T} (\cmd{transpose-characters}) command.  Normally, \key{C-T}
transposes the two characters on either side of the cursor and moves the
cursor forward one character.  Repeating the command several times
``drags'' a character to the right.  (Remember that \Def{point} is
considered to be between two characters, even though the visible cursor
in your terminal is on only one of them.)  When given at the end of a
line, rather than switching the last character of the line with the line
separator, which would be useless, \key{C-T} transposes the last two
characters on the line.  So, if you catch your transposition error right
away, you can fix it with just a \key{C-T}.  If you don't catch it so
fast, you must move the cursor back to between the two characters.
\par\noindent
To transpose two lines, use the \key{C-X~C-T} (\cmd{transpose-lines})
command.  The line containing the cursor is exchanged with the line
above it; the cursor is left at the beginning of the line following its
original position.

\subsection{Checking and Correcting Spelling}

When you write a paper, you should correct its spelling at some point
close to finishing it.  To correct the entire buffer, do
\key{ESC~X spell-buffer}.  This invokes the \file{spell\,(1)}
program, which prints a list of all the misspelled words.
\Jove{} catches the list and places it in a \jove{} buffer called
\out{Spell}.  You are given an opportunity to delete from that buffer
any words that aren't really errors; then \jove{} looks up each
misspelled word and remembers where it is in the buffer being corrected.
Then you can go forward to each misspelled word with \key{C-X~C-N}
(\cmd{next-error}) and backward with \key{C-X~C-P}
(\cmd{previous-error}).  See the section entitled
{\em Error Message Parsing\/}.

\section{File Handling}

The basic unit of stored data is the file.  Each program, each paper,
lives usually in its own file.  To edit a program or paper, the editor
must be told the name of the file that contains it.  This is called
\Def{visiting} a file. To make your changes to the file permanent on
disk, you must \Def{save} the file.

\subsection{Visiting Files}

\begin{description}
\item[{C-X~C-R}]
Visit (read) a file.
\item[{C-X~C-V}]
Same as C-X C-R\nroff{\(dg.}\footnote{
\nroff{\(dg}
Often \key{C-X~C-V} is bound to \cmd{view-file} which visits a file in
read-only mode.
}
\item[{C-X~C-S}]
Save the visited file.
\item[{ESC~\tilde{}}]
Tell \jove{} to forget that the buffer has been changed.
\end{description}
\Def{Visiting} a file means copying its contents into \jove{} where you
can edit them.
\Jove{} remembers the name of the file you visited.  Unless you use the
multiple buffer feature of \jove{} you can only be visiting one file at
a time.  The name of the current selected buffer is visible in the mode
line.
\par\noindent
The changes you make with \jove{} are made in a copy inside \jove{}. The
file itself is not changed.  The changed text is not permanent until you
\Def{save} it in a file.  The first time you change the text, an
asterisk appears at the end of the mode line; this indicates that the
text contains fresh changes which will be lost unless you save them.
\par\noindent
To visit a file, use the command \key{C-X~C-V}.  Follow the command with
the name of the file you wish to visit, terminated by a \key{Return}.
You can abort the command by typing \key{C-G}, or edit the filename with
many of the standard \jove{} commands (e.g., \key{C-A}, \key{C-E},
\key{C-F}, \key{ESC~F}, \key{ESC~Rubout}).  If the filename you wish to
visit is similar to the filename in the mode line (the default
filename), you can type \key{C-R} to insert the default and then edit
it.  If you do type a \key{Return} to finish the command, the new file's
text appears on the screen, and its name appears in the mode line.  In
addition, its name becomes the new default filename.
\par\noindent
If you wish to save the file and make your changes permanent, type
\key{C-X~C-S}.  After the save is finished, \key{C-X~C-S} prints the
filename and the number of characters and lines that it wrote to the
file.  If there are no changes to save (no asterisk at the end of the
mode line), the file is not saved; otherwise the changes saved and the
asterisk at the end of the mode line will disappear.
\par\noindent
What if you want to create a file?  Just visit it.
\Jove{} prints \out{(New file)} but aside from that behaves as if you
had visited an existing empty file.  If you make any changes and save
them, the file is created.  If you visit a nonexistent file
unintentionally (because you typed the wrong filename), go ahead and
visit the file you meant.  If you don't save the unwanted file, it is
not created.
\par\noindent
If you alter one file and then visit another in the same buffer, \jove{}
offers to save the old one.  If you answer \key{YES}, the old file is
saved; if you answer \key{NO}, all the changes you have made to it since
the last save are lost.  You should not type ahead after a file visiting
command, because your type-ahead might answer an unexpected question in
a way that you would regret.
\par\noindent
Sometimes you will change a buffer by accident.  Even if you undo the
effect of the change by editing, \jove{} still knows that ``the buffer
has been changed''.  You can tell \jove{} to pretend that there have
been no changes with the \key{ESC~\tilde{}} command
(\cmd{make-buffer-unmodified}).  This command simply clears the
``modified'' flag which says that the buffer contains changes which need
to be saved.  Even if the buffer really {\em is\/} changed \jove{} will
still act as if it were not.
\par\noindent
If \jove{} is about to save a file and sees that the date of the version
on disk does not match what \jove{} last read or wrote, \jove{} notifies
you of this fact, and asks what to do, because this probably means that
something is wrong.  For example, somebody else may have been editing
the same file.  If this is so, there is a good chance that your work or
his work will be lost if you don't take the proper steps.  You should
first find out exactly what is going on.  If you determine that somebody
else has modified the file, save your file under a different filename
and then \file{diff\,(1)} the two files to merge the two sets of
changes.  (The \file{patch\,(1)} command is useful for applying the
results of context diffs directly).  Also get in touch with the other
person so that the files don't diverge any further.

\subsection{How to Undo Drastic Changes to a File}

If you have made several extensive changes to a file and then change
your mind about them, and you haven't yet saved them, you can get rid of
them by reading in the previous version of the file.  You can do this
with the \key{C-X~C-V} command, to visit the unsaved version of the
file.

\subsection{Recovering from system/editor crashes}

\Jove{} does not have \Def{Auto Save} mode, but it does provide a way to
recover your work in the event of a system or editor crash.  \Jove{}
saves information about the files you're editing every so many changes
to a buffer to make recovery possible.  Since a relatively small amount
of information is involved it's hardly even noticeable when \jove{} does
this.  The variable \cmd{sync-frequency} says how often to save the
necessary information, and the default is every 50 changes.  50 is a
very reasonable number: if you are writing a paper you will not lose
more than the last 50 characters you typed, which is less than the
average length of a line.  After a crash you can recover your work
by invoking \jove{} as:
\begin{quote}
\% \file{jove --r}
\end{quote}

\subsection{Miscellaneous File Operations}

\key{ESC~X write-file $<$file$><$return$>$} writes the contents of the
buffer into the file {\it $<$file$>$}, and then visits that file.  It
can be thought of as a way of ``changing the name'' of the file you are
visiting.  Unlike \key{C-X~C-S}, \cmd{write-file} saves even if the
buffer has not been changed. \key{C-X~C-W} is another way of getting
this command.
\par\noindent
\key{ESC~X insert-file $<$file$><$return$>$} inserts the contents of
{\it $<$file$>$} into the buffer at point, leaving point unchanged
before the contents.  You can also use \key{C-X~C-I} to get this
command.
\par\noindent
\key{ESC~X write-region $<$file$><$return$>$} writes the region (the
text between point and mark) to the specified file.  It does not set the
visited filename.  The buffer is not changed.
\par\noindent
\key{ESC~X append-region $<$file$><$return$>$} appends the region to
{\it $<$file$>$}.  The text is added to the end of {\it $<$file$>$}.

\section{Using Multiple Buffers}

When we speak of ``the buffer'', which contains the text you are
editing, we have given the impression that there is only one.  In fact,
there may be many of them, each with its own body of text.  At any time
only one buffer can be \Def{selected} and available for editing, but it
isn't hard to switch to a different one.  Each buffer individually
remembers which file it is visiting, what modes are in effect, and
whether there are any changes that need saving.
\begin{description}
\item[{C-X~B}]
Select or create a buffer.
\item[{C-X~C-F}]
Visit a file in its own buffer.
\item[{C-X~C-B}]
List the existing buffers.
\item[{C-X~K}]
Kill a buffer.
\end{description}
Each buffer in \jove{} has a single name, which normally doesn't change.
A buffer's name can be any length.  The name of the currently selected
buffer and the name of the file visited in it are visible in the mode
line when you are at top level.  A newly started \jove{} has only one
buffer, named \out{Main}, unless you specified files to edit in the
shell command that started \jove{}.

\subsection{Creating and Selecting Buffers}

To create a new buffer, you need only think of a name for it (say,
\eg{FOO}) and then do \key{C-X~B FOO$<$return$>$}, which is the command
\key{C-X~B} (\cmd{select-buffer}) followed by the name.  This makes a
new, empty buffer (if one by that name didn't previously exist) and
selects it for editing.  The new buffer is not visiting any file, so if
you try to save it you will be asked for the filename to use.  Each
buffer has its own major mode; the new buffer's major mode is \cmd{Text}
mode by default.
\par\noindent
To return to buffer \eg{FOO} later after having switched to another,
the same command \key{C-X~B FOO$<$return$>$} is used, since \key{C-X~B}
can tell whether a buffer named \eg{FOO} exists already or not.
\key{C-X~B Main$<$return$>$} reselects the buffer \out{Main} that \jove{}
started out with.  Just \key{C-X~B$<$return$>$} reselects the previous
buffer.  Repeated \key{C-X~B$<$return$>$}'s alternate between the last
two buffers selected.
\par\noindent
You can also read a file into its own newly created buffer, all with one
command: \key{C-X~C-F} (\cmd{find-file}), followed by the filename.  The
name of the buffer is the last element of the file's pathname. \key{C-F}
stands for ``Find'', because if the specified file already resides in a
buffer in your \jove{} that buffer is reselected.  So you need not
remember whether you have brought the file in already or not.  A buffer
created by \key{C-X~C-F} can be reselected later with \key{C-X~B} or
\key{C-X~C-F}, whichever you find more convenient.  Nonexistent files
can be created with \key{C-X~C-F} just as they can with \key{C-X~C-V}.

\subsection{Using Existing Buffers}

To get a list of all the buffers that exist, do \key{C-X~C-B}
(\cmd{list-buffers}).  Each buffer's type, name, and visited filename is
printed.  An asterisk before the buffer name indicates a buffer which
contains changes that have not been saved. The number that appears at
the beginning of a line in a \key{C-X~C-B} listing is that buffer's
\Def{buffer number}.  You can select a buffer by typing its number in
place of its name.  If a buffer with that number doesn't already exist,
a new buffer is created with that number as its name.
\par\noindent
If several buffers have modified text in them, you should save some of
them with \key{C-X~C-M} (\cmd{write-modified-files}).  This finds all
the buffers that need saving and then saves them.  Saving the buffers
this way is much easier and more efficient (but more dangerous) than
selecting each one and typing \key{C-X~C-S}.  If you give \key{C-X~C-M}
an argument, \jove{} will ask for confirmation before saving each
buffer.
\par\noindent
\key{ESC~X rename-buffer $<$new name$><$return$>$} changes the name of
the currently selected buffer.
\par\noindent
\key{ESC~X erase-buffer $<$buffer name$><$return$>$} erases the contents
of the {\it $<$buffer name$>$} without deleting the buffer entirely.

\subsection{Killing Buffers}

After you use a \jove{} for a while, it may fill up with buffers which
you no longer need.  Eventually you can reach a point where trying to
create any more results in an \out{out of memory} or \out{out of lines}
error.  When this happens you will want to kill some buffers with the
\key{C-X~K} (\cmd{delete-buffer}) command.  You can kill the buffer
\eg{FOO} by doing \key{C-X~K FOO$<$return$>$}.  If you type
\key{C-X~K $<$return$>$} \jove{} will kill the previously selected
buffer.  If you try to kill a buffer that needs saving \jove{} will ask
you to confirm it.
\par\noindent
If you need to kill several buffers, use the command
\cmd{kill-some-buffers}.  This prompts you with the name of each buffer
and asks for confirmation before killing that buffer.

\section{Controlling the Display}

Since only part of a large file will fit on the screen, \jove{} tries to
show the part that is likely to be interesting.  The display control
commands allow you to see a different part of the file.
\begin{description}
\item[{C-L}]
Reposition point at a specified vertical position,
{\em or\/} clear and redraw the screen with point in the same place.
\item[{C-V}]
Scroll forwards (a screen or a few lines).
\item[{ESC~V}]
Scroll backwards.
\item[{C-Z}]
Scroll forward some lines.
\item[{ESC~Z}]
Scroll backwards some lines.
\end{description}
The terminal screen is rarely large enough to display all of your file.
If the whole buffer doesn't fit on the screen, \jove{} shows a
contiguous portion of it, containing \Def{point}.  It continues to show
approximately the same portion until point moves outside of what is
displayed; then \jove{} chooses a new portion centered around the new
\Def{point}. This is \jove{}s guess as to what you are most interested
in seeing, but if the guess is wrong, you can use the display control
commands to see a different portion.  The available screen area through
which you can see part of the buffer is called \Def{the window}, and the
choice of where in the buffer to start displaying is also called
\Def{the window}.  (When there is only one window, it plus the mode line
and the input line take up the whole screen).
\par\noindent
First we describe how \jove{} chooses a new window position on its own.
The goal is usually to place \Def{point} half way down the window.  This
is controlled by the variable \cmd{scroll-step}, whose value is the
number of lines above the bottom or below the top of the window that the
line containing point is placed.  A value of 0 (the initial value) means
center \Def{point} in the window.
\par\noindent
The basic display control command is \key{C-L} (\cmd{redraw-display}).
In its simplest form, with no argument, it tells \jove{} to choose a new
window position, centering point half way from the top as usual.
\par\noindent
\key{C-L} with a positive argument chooses a new window so as to put
point that many lines from the top.  An argument of zero puts point on
the very top line. A negative argument puts point that many lines from
the bottom.  Point does not move with respect to the text; rather, the
text and point move rigidly on the screen.
\par\noindent
If point stays on the same line, the window is first cleared and then
redrawn.  Thus, two \key{C-L}'s in a row are guaranteed to clear the
current window. \key{ESC} \key{C-L} will clear and redraw the entire
screen.
\par\noindent
The \Def{scrolling} commands \key{C-V}, \key{ESC~V}, \key{C-Z}, and
\key{ESC~Z}, let you move the whole display up or down a few lines.
\key{C-V} (\cmd{next-page}) with an argument shows you that many more
lines at the bottom of the screen, moving the text and point up together
as \key{C-L} might.
\key{C-V} with a negative argument shows you more lines at the top of
the screen, as does \key{ESC~V} (\cmd{previous-page}) with a positive
argument.
\par\noindent
To read the buffer a window at a time, use the \key{C-V} command with no
argument.  It takes the last line at the bottom of the window and puts
it at the top, followed by nearly a whole window of lines not visible
before.  Point is put at the top of the window.  Thus, each \key{C-V}
shows the ``next page of text'', except for one line of overlap to
provide context.  To move backward, use \key{ESC~V} without an argument,
which moves a whole window backwards (again with a line of overlap).
\par\noindent
\key{C-Z} and \key{ESC~Z} scroll one line forward and one line backward,
respectively.  These are convenient for moving in units of lines without
having to type a numeric argument.

\subsection{Multiple Windows}

\Jove{} allows you to split the screen into two or more \Def{windows}
and use them to display parts of different files, or different parts of
the same file.
\begin{description}
\item[{C-X~2}]
Divide the current window into two smaller ones.
\item[{C-X~1}]
Delete all windows but the current one.
\item[{C-X~D}]
Delete current window.
\item[{C-X~N}]
Switch to the next window.
\item[{C-X~P}]
Switch to the previous window.
\item[{C-X~O}]
Same as \key{C-X~P}.
\item[{C-X~\carat{}}]
Make this window bigger.
\item[{ESC~C-V}]
Scroll the other window.
\end{description}
When using \Def{multiple window} mode, the text portion of
the screen is divided into separate parts called \Def{windows}, which
can display different pieces of text.  Each window can display different
files, or parts of the same file.  Only one of the windows is
\Def{active}; that is the window which the cursor is in.  Editing
normally takes place in that window alone.  To edit in another window,
you would give a command to move the cursor to the other window, and
then edit there.
\par\noindent
Each window displays a mode line for the buffer it's displaying.  This
is useful to keep track of which window corresponds with which file.  In
addition, the mode line serves as a separator between windows.  By
setting the variable \cmd{mode-line-should-standout} to ``on'' you can
have \jove{} display the mode-line in reverse video (assuming your
particular terminal has the reverse video capability).
\par\noindent
The command \key{C-X~2} (\cmd{split-current-window}) enters multiple
window mode.  A new mode line appears across the middle of the screen,
dividing the text display area into two halves.  Both windows contain
the same buffer and display the same position in it, namely where point
was at the time you issued the command.  The cursor moves to the second
window.
\par\noindent
To return to viewing only one window, use the command \key{C-X~1}
(\cmd{delete-other-windows}).  The current window expands to fill the
whole screen, and the other windows disappear until the next
\key{C-X~2}.  (The buffers and their contents are unaffected by any of
the window operations).
\par\noindent
While there is more than one window, you can use \key{C-X~N}
(\cmd{next-window}) to switch to the next window, and \key{C-X~P}
(\cmd{previous-window}) to switch to the previous one.  If you are in
the bottom window and you type \key{C-X~N}, you will be placed in the
top window, and the same kind of thing happens when you type \key{C-X~P}
in the top window, namely you will be placed in the bottom window.
\key{C-X~O} is the same as \key{C-X~P}.  It stands for ``other window''
because when there are only two windows, repeated use of this command
will switch between the two windows.
\par\noindent
Often you will be editing one window while using the other just for
reference.  Then, the command \key{ESC~C-V} (\cmd{page-next-window}) is
very useful.  It scrolls the next window, as if you switched to the next
window, typed \key{C-V}, and switched back, without your having to do
all that.  With a negative argument, \key{ESC} \key{C-V} will do an
\key{ESC~V} in the next window.
\par\noindent
When a window splits, both halves are approximately the same size.  You
can redistribute the screen space between the windows with the
\key{C-X~\carat{}} (\cmd{grow-window}) command.  It makes the currently
selected window grow one line bigger, or as many lines as is specified
with a numeric argument.  Use \key{ESC~X} (\cmd{shrink-window}) to make
the current window smaller.

\subsection{Multiple Windows and Multiple Buffers}

Buffers can be selected independently in each window.  The \key{C-X~B}
command selects a new buffer in whichever window contains the cursor.
Other windows' buffers do not change.
\par\noindent
You can view the same buffer in more than one window.  Although the same
buffer appears in both windows, they have different values of point, so
you can move around in one window while the other window continues to
show the same text.  Then, having found one place you wish to refer to,
you can go back into the other window with \key{C-X~O} or \key{C-X~P} to
make your changes.
\par\noindent
If you have the same buffer in both windows, you must beware of trying
to visit a different file in one of the windows with \key{C-X~C-V},
because if you bring a new file into this buffer, it will replaced the
old file in {\em both\/} windows.  To view different files in different
windows, you must switch buffers in one of the windows first (with
\key{C-X~B} or \key{C-X~C-F}, perhaps).
\par\noindent
A convenient ``combination'' command for viewing something
in another window is \key{C-X~4} (\cmd{window-find}).  With this command
you can ask to see any specified buffer, file or tag in the other
window.  Follow the \key{C-X~4} with either \key{B} and a buffer name,
\key{F} and a filename, or \key{T} and a tag name.  This switches to the
other window and finds there what you specified.  If you were previously
in one-window mode, multiple-window mode is entered.
\begin{description}
\item[{C-X~4~B}]
is similar to \key{C-X~2~C-X B}.
\item[{C-X~4~F}]
 is similar to \key{C-X~2~C-X C-F}.
\item[{C-X~4~T}]
is similar to \key{C-X~2~C-X T}.
\end{description}
The difference is one of efficiency, and also that \key{C-X~4} works
equally well if you are already using two windows.

\section{Processes Under JOVE}

Another feature in \jove{} is its ability to interact with
\UNIX{}\nroff{*}\footnote{
\nroff{*}
or whatever system \jove{} is running on; so please read ``Vermin Might
Spawn'' for \UNIX{} if you happen to be on that system. (any semblance
to existing acronyms is purely coincidental\ldots)
}
in a
useful way.  You can run other \UNIX{} commands from \jove{} and catch
their output in \jove{} buffers.  In this chapter we will discuss the
different ways to run and interact with \UNIX{} commands.

\subsection{Non-interactive \UNIX{} commands}

To run a \UNIX{} command from \jove{} just type \key{C-X~!} followed by
the name of the command terminated with \key{Return}.  For example, to
get a list of all the users on the system, you do:
\begin{quote}
\key{C-X~! who$<$return$>$}
\end{quote}
Then \jove{} picks a reasonable buffer in which the output from the
command will be placed.  E.g., \file{who} uses a buffer called
\out{[who]}; \file{ps~alx} uses \out{[ps]}; and \file{fgrep~--n~foo~*.c}
uses \out{[fgrep]}.  If \jove{} wants to use a buffer that already
exists it first erases the old contents.  If the buffer it selects holds
a file, not output from a previous shell command, you must first delete
that buffer with \key{C-X~K}.
\par\noindent
Once \jove{} has picked a buffer it puts that buffer in a window so you
can see the command's output as it is running.  If there is only one
window \jove{} will automatically make another one.  Otherwise, \jove{}
tries to pick the most convenient window which isn't the current one.
\par\noindent
It's not a good idea to type anything while the command is running, since
\jove{} won't see the characters (thus won't execute them) until the
command finishes, so you may forget what you've typed\nroff{\(dg.}\footnote{
\nroff{\(dg}
Yes, the bug that caused \jove{} to stop updating the display when it
sees type-ahead characters here, has been fixed.
}.
\par\noindent
If you want to interrupt the command for some reason (perhaps you
mistyped it, or you changed your mind) you can type the
\cmd{interrupt-character}, usually \key{C-]}.  Typing
this inside \jove{} while a process is running is the same as typing
\key{C-C} when you are outside \jove{} namely the process stops in a
hurry.
\par\noindent
When the command finishes, \jove{} puts you back in the window in which
you started.  Then it prints a message indicating whether or not the
command completed successfully in its (the command's) opinion.  That is,
if the command had what it considers an error (or you interrupt it with
\key{C-]}) \jove{} will print an appropriate message.

\subsection{Limitations of Non-Interactive Processes}

The reason these are called non-interactive processes is that you can't
type any input to them; you can't interact with them; they can't ask you
questions because there is no way for you to answer.  For example, you
can't run a command interpreter (a shell), or \file{mail} or
\file{crypt} with \key{C-X~!} because there is no way to provide it with
input.  Remember that \jove{} (not the process in the window) is
listening to your keyboard, and \jove{} waits until the process dies
before it looks at what you type.
\par\noindent
\key{C-X~!} is useful for running commands that do some output and then
exit.  For example, it's very useful to use with the C compiler to catch
compilation error messages (see Compiling C Programs), or with the
\file{grep} commands.

\subsection{Interactive Processes --- Run a Shell in a Window}

Most versions of \jove{}\nroff{*}\footnote{
\nroff{*}
Currently, all but the smallest \UNIX{} versions, and {\sc\lowercase{VMS}}.
}
have the capability of running interactive processes.  This is more
useful than non-interactive processes for certain types of jobs:
\begin{itemize}
\item
You can go off and do some editing while the command is running.
This is useful for commands that do sporadic output and run for fairly
long periods of time.
\item
Unlike non-interactive processes, you can type input to these.  In
addition, you can edit what you type with the power of all the \jove{}
commands {\em before\/} you send the input to the process.  This is a
really important feature, and is especially useful for running a shell
in a window.
\item
Because you can continue with normal editing while one of the processes
is running, you can create a bunch of contexts and manage them (select
them, delete them, or temporarily put them aside) with \jove{}s window
and buffer mechanisms.
\end{itemize}
Although we may have given an image of processes being attached to
\Def{windows},in fact they are attached to \Def{buffers}.  Therefore,
once an \Def{i-process} is running you can select another buffer into
that window, or if you wish you can delete the window altogether.  If
you reselect that buffer later it will be up to date.  That is, even
though the buffer wasn't visible it was still receiving output from the
process.  You don't have to worry about missing anything when the buffer
isn't visible.

\subsection{Advantages of Running Processes in \jove{} Windows.}

There are several advantages to running a shell in a window.  What you
type isn't seen immediately by the process; instead \jove{} waits until
you type an entire line before passing it on to the process to read.
This means that before you type \key{$<$return$>$} all of \jove{}s
editing capabilities are available for fixing errors on your input line.
If you discover an error at the beginning of the line, rather than
erasing the whole line and starting over, you can simply move to the
error, correct it, move back and continue typing.
\par\noindent
Another feature is that you have the entire history of your session in a
\jove{} buffer.  You don't have to worry about output from a command
moving past the top of the screen.  If you missed some output you can
move back through it with \key{ESC~V} and other commands.  In addition,
you can save yourself retyping a command (or a similar one) by sending
edited versions of previous commands, or edit the output of one command
to become a list of commands to be executed (``immediate shell
scripts'').

\subsection{Differences between Normal and I-process Buffers}

\Jove{} behaves differently in several ways when you are in an
\Def{i-process} buffer.  Most obviously, \key{$<$return$>$} does
different things depending on both your position in the buffer and on
the state of the process.  In the normal case, when point is at the end
of the buffer, \key{Return} does what you'd expect: it inserts a
line-separator and then sends the line to the process.  If you are
somewhere else in the buffer, possibly positioned at a previous command
that you want to edit, \key{Return} will place a copy of that line (with
the prompt discarded if there is one) at the end of the buffer and move
you there.  Then you can edit the line and type \key{Return} as in the
normal case.  If the process has died for some reason, \key{Return} does
nothing.  It doesn't even insert itself.  If that happens unexpectedly,
you should type \key{ESC~X list-processes$<$return$>$} to get a list of
each process and its state.  If your process died abnormally,
\cmd{list-processes} may help you figure out why.

\subsection{How to Run a Shell in a Window}

Type \key{ESC~X shell$<$return$>$} to start up a shell.  As with
\key{C-X~!}, \jove{} will create a buffer, called \out{*shell*}, and
select a window for this new buffer.  But unlike \key{C-X~!} you will be
left in the new window.  Now, the shell process is said to be attached
to \out{*shell*}.
%
% input file: jove.3
%
\section{Directory Handling}

To save having to use absolute pathnames when you want to edit a nearby
file \jove{} allows you to move around the \UNIX{} filesystem just as
the C-shell does.  These commands are:
\begin{description}
\item[{cd~{\it dir\/}}]
Change to the specified directory.
\item[{pushd~[{\it dir\/}]}]
Like \cmd{cd}, but save the old directory on the directory stack.  With
no directory argument, simply exchange the top two directories on the
stack and \cmd{cd} to the new top.
\item[{popd}]
Take the current directory off the stack and \cmd{cd} to the directory
now at the top.
\item[{dirs}]
Display the contents of the directory stack.
\end{description}
The names and behavior of these commands were chosen to mimic those in
the C-shell.

\section{Editing C Programs}

This section details the support provided by \jove{} for working on C
programs.

\subsection{Indentation Commands}

To save having to lay out C programs ``by hand'', \jove{} has an idea of
the correct indentation of a line, based on the surrounding context.
When you are in C Mode, \jove{} treats tabs specially --- typing a tab
at the beginning of a new line means ``indent to the right place''.
Closing braces are also handled specially, and are indented to match the
corresponding open brace.

\subsection{Parenthesis and Brace Matching}

To check that parentheses and braces match the way you think they do,
turn on \cmd{Show Match} mode (\key{ESC~X show-match-mode}).  Then,
whenever you type a close brace or parenthesis, the cursor moves
momentarily to the matching opener, if it's currently visible.  If it's
not visible, \jove{} displays the line containing the matching opener on
the message line.

\subsection{C Tags}

Often when you are editing a C program, especially someone else's code,
you see a function call and wonder what that function does.  You then
search for the function within the current file and if you're lucky find
the definition, finally returning to the original spot when you are
done.  However, if are unlucky, the function turns out to be external
(defined in another file) and you have to suspend the edit, \file{grep}
for the function name in every \file{*.c} that might contain it, and
finally visit the appropriate file.
\par\noindent
To avoid this diversion or the need to remember which function is
defined in which file, Berkeley \UNIX{} has a program called
\file{ctags\,(1)}, which takes a set of source files and looks for
function definitions, producing a file called \file{tags} as its output.
\par\noindent
\Jove{} has a command called \key{C-X~T} (\cmd{find-tag}) that prompts
you for the name of a function (a \Def{tag}), looks up the tag reference
in the previously constructed tags file, then visits the file containing
that tag in a new buffer, with point positioned at the definition of the
function.  There is another version of this command, namely
\cmd{find-tag-at-point}, that uses the identifier at \Def{point}.
\par\noindent
So, when you've added new functions to a module, or moved some old ones
around, run the \file{ctags} program to regenerate the \file{tags} file.
\Jove{} looks in the file specified in the \cmd{tag-file} variable.  The
default is ``\file{./tags}'', that is, the tag file in the current
directory.  If you wish to use an alternate tag file, you use
\key{C-U~C-X~T}, and \jove{} will prompt for a file name.  If you find
yourself specifying the same file again and again, you can set
\cmd{tag-file} to that file, and run \cmd{find-tag} with no numeric
argument.
\par\noindent
To begin an editing session looking for a particular tag, use
the \cmd{--t tag} command line option to \jove{}.
For example, say you wanted to look at the file containing the tag
\eg{SkipChar}, you would invoke \jove{} as:
\begin{quote}
\% \file{jove --t SkipChar}
\end{quote}

\subsection{Compiling Your Program}

You've typed in a program or altered an existing one and now you want to
run it through the compiler to check for errors.  To save having to
suspend the edit, run the compiler, scribble down error messages, and
then resume the edit, \jove{} allows you to compile your code while in
the editor.  This is done with the \key{C-X~C-E} (\cmd{compile-it})
command.  If you run \cmd{compile-it} with no argument it runs the
\UNIX{} \file{make\,(1)} program into a buffer; If you need a special
command or want to pass arguments to \file{make}, run \cmd{compile-it}
with any argument (\key{C-U} is good enough) and you will be prompted
for the command to execute.
\par\noindent
If any error messages are produced, they are treated specially by
\jove{}. That treatment is the subject of the next section.

\subsection{Error Message Parsing and Spelling Checking}

\Jove{} knows how to interpret the error messages from many \UNIX{}
commands; In particular, the messages from \file{cc}, \file{grep~--n}
and \file{lint} can be understood.  After running the \cmd{compile-it}
command, the \cmd{parse-errors} command is automatically executed, and
any errors found are displayed in a new buffer.  The files whose names
are found in parsing the error messages are each brought into \jove{}
buffers and the point is positioned at the first error in the first
file.  The commands \cmd{current-error}, \key{C-X~C-N}
(\cmd{next-error}), and \key{C-X~C-P} (\cmd{previous-error}) can be used
to traverse the list of errors.
\par\noindent
If you already have a file called \file{errs} containing, say, C
compiler messages then you can get \jove{} to interpret the messages by
invoking it as:
\begin{quote}
\% \file{jove --p errs}
\end{quote}
\Jove{} has a special mechanism for checking the the spelling of a
document; It runs the \file{spell\,(1)} program into a buffer.
You then delete from this buffer all those words that are not spelling
errors and then \jove{} runs the \cmd{parse-spelling-errors} command to
yield a list of errors just as in the last section.
\par\noindent
If you want \jove{} to use {\em interactive} processes in the
\cmd{spell} and \cmd{compile-it} commands, so that you can continue your
editing work, set the variable \cmd{i-process-parse} to ``on''.

\section{Simple Customization}

\subsection{Major Modes}

To help with editing particular types of file, say a paper or a C program,
\jove{} has several \Def{major modes}.
These are as follows:
\begin{description}
\item[{Text mode}]
This is the default major mode.  Nothing special is done.
\item[{Fundamental}]
This is like Text mode except words are delimited by whitespace only.
\item[{C mode}]
This mode affects the behavior of the tab and parentheses characters.
Instead of just inserting the tab, \jove{} determines where the text
``ought'' to line up for the C language and tabs to that position
instead.  The same thing happens with the close brace and close
parenthesis; they are tabbed to the ``right'' place and then inserted.
Using the \cmd{auto-execute-command} command, you can make \jove{} enter
\cmd{C Mode} whenever you edit a file whose name ends in \file{.c}.
\item[{Lisp mode}]
This mode is analogous to \cmd{C Mode}, but performs the indentation
needed to lay out Lisp programs properly.  Note also the
\cmd{grind-s-expr} command that prettyprints an \Def{s-expression},
and the \cmd{\{for,back\Rbrace{}ward-s-expression},
\cmd{\{for,back\Rbrace{}ward-list} and
\cmd{kill-s-expression} commands (which are also available in other
major modes.)
\item[{Perl mode}\nroff{\(dg}\footnotemark]\footnotetext{
\nroff{\(dg}
\file{perl} is a programming language designed by Larry Wall, which combines
many desirable features of C, sh, sed and awk.
}
This mode is much like \cmd{C Mode}, but differs in a few small but
essential ways. For example it should (and does) not recognize C style
comments.
\end{description}

\subsection{Minor Modes}

In addition to the major modes, \jove{} has a set of minor modes.
These are as follows:
\begin{description}
\item[{Auto Indent}]
In this mode, \jove{} indents each line the same way as that above it.
That is, the \key{Return} key in this mode acts as the \key{Linefeed}
key ordinarily does.
\item[{Show Match}]
Move the cursor momentarily to the matching opening parenthesis when a
closing parenthesis is typed.
\item[{Auto Fill}]
In \cmd{Auto Fill} mode, a newline is automatically inserted when the
line length exceeds the right margin.  This way, you can type a whole
paper without having to use the \key{Return} key.
\item[{Over Write}]
In this mode, any text typed in will replace the previous contents.
(The default is for new text to be inserted and ``push'' the old along.)
This is useful for editing an already-formatted diagram in which you
want to change some things without moving other things around on the
screen.
\item[{Word Abbrev}]
In this mode, every word you type is compared to a list of word
abbreviations; whenever you type an abbreviation, it is replaced by the
text that it abbreviates.  This can save typing if a particular word or
phrase must be entered many times.  The abbreviations and their
expansions are held in a file with lines that looks like:
\begin{quote}
abbrev:phrase
\end{quote}
This file can be set up in your \file{\tilde{}/.\,joverc} with the
\cmd{read-word-abbrev-file} command. Then, whenever you are editing a
buffer in \cmd{Word Abbrev} mode, \jove{} checks for the abbreviations
you've given.
\par\noindent
See also the commands \cmd{read-word-abbrev-file},
\cmd{write-word-abbrev-file}, \cmd{edit-word-abbrevs},
\cmd{define-global-word-abbrev}, \cmd{define-mode-word-abbrev},
and \cmd{ bind-macro-to-word-abbrev}, and the variable
\cmd{auto-case-abbrev}.
\item[{View Mode}]
In this mode, you cannot in any way execute commands that modify the
buffer.  Buffers visiting read-only files are automatically set up in
this mode.
\end{description}

\subsection{Variables}

\Jove{} can be tailored to suit your needs by changing the values of
variables.  A \jove{} variable can be given a value with the \cmd{set}
command, and its value displayed with the \cmd{print} command.
\par\noindent
The variables \jove{} understands are listed along with the commands
in the alphabetical list at the end of this document.

\subsection{Key Re-binding}

Many of the commands built into \jove{} are not bound to specific keys.
The command handler in \jove{} is used to invoke these commands and is
activated by the \cmd{execute-extended-command} command (\key{ESC~X}).
When the name of a command typed in is unambiguous, that command will be
executed.  Since it is very slow to have to type in the name of each
command every time it is needed, \jove{} makes it possible to \Def{bind}
commands to keys.  When a command is \Def{bound} to a key any future
hits on that key will invoke that command.  All the printing characters
are initially bound to the command \cmd{self-insert}.  Thus, typing any
printing character causes it to be inserted into the text.  Any of the
existing commands can be bound to any key.  (A \Def{key} may actually be
a \Def{control character} or an \Def{escape sequence} as explained
previously under \Def{Command Input Conventions}).
\par\noindent
Since there are more commands than there are keys, two keys are treated
as \Def{prefix} commands.  When a key bound to one of the prefix
commands is typed, the next character typed is interpreted on the basis
that it was preceded by one of the prefix keys.  Initially \key{\carat{}X}
and \key{ESC} are the prefix keys and many of the built in commands are
initially bound to these ``two stroke'' keys.  (For historical reasons,
the \key{Escape} key is often referred to as ``\key{Meta}'').

\subsection{Keyboard Macros}

Although \jove{} has many powerful commands, you often find that you
have a task that no individual command can do.
\Jove{} allows you to define your own commands from sequences of
existing ones ``by example''; Such a sequence is termed a \Def{macro}.
The procedure is as follows:  First you type the \cmd{start-remembering}
command, usually bound to \key{C-X~(}.  Next you ``perform'' the
commands which as they are being executed are also remembered, which
will constitute the body of the macro.  Then you give the
\cmd{stop-remembering} command, usually bound to \key{C-X~)}.  You now
have a \Def{keyboard macro}.  To run this command sequence again, use
the command \cmd{execute-keyboard-macro}, usually bound to \key{C-X~E}.
You may find this bothersome to type and re-type, so there is a way to
bind the macro to a key.  First, you must give the keyboard macro a name
using the \cmd{name-keyboard-macro} command.  Then the binding is made
with the \cmd{bind-macro-to-key} command.  We're still not finished
because all this hard work will be lost if you leave \jove{}.  What you
do is to save your macros into a file with the \cmd{write-macros-to-file}
command.  To retrieve your macros in the next editing session (but not
their bindings), you can simply execute the \cmd{source} command on that
file.

\subsection{Initialization Files}

Users will likely want to modify the default key bindings to their
liking.  Since it would be quite annoying to have to set up the bindings
each time \jove{} is started up, \jove{} has the ability to read in a
``startup'' file.  Whenever \jove{} is started, it reads commands from
the file \file{.\,joverc}\nroff{*}\footnote{
\nroff{*}
\file{jove.rc} on non-\UNIX{} systems.
}
in the user's home directory.  These commands
are read as if they were typed to the command handler (\key{ESC~X})
during an edit.  There can be only one command per line in the startup
file.  If there is a file \file{/usr/local/lib/joverc}\nroff{\(dg,}\footnote{
\nroff{\(dg}
or wherever your guru has installed \jove{}s auxiliary files on your
system.
},
then this file will be read before the user's \file{\tilde{}/.\,joverc}
file.  This can be used to set up a system-wide default startup mode for
\jove{} that is tailored to the needs of that system.  If there is a
file \file{.\,joverc} in the current directory, this will be read after
the user's \file{\tilde{}/.\,joverc} file.  This can be used, for
instance, to change the C mode indentation to the need of other people's
software.
\par\noindent
The \cmd{source} command can be used to read commands from a specified
file at any time during an editing session, even from inside the
\file{.\,joverc} file.  This means that a macro can be used to change
the key bindings, e.g., to enter a mode, by reading from a specified
file which contains all the necessary bindings.

\cleardoublepage

%=======================================================================
% $Log: joveman.tex,v $
% Revision 14.30  1993/02/09  23:08:24  tom
% adjust date.
%
% Revision 14.26  1992/08/26  23:57:11  tom
% add RCS directives
%
%=======================================================================
