@c $Id$

@node Running Terminal Based Applications
@chapter Running Terminal Based Applications.

You can use the terminal emulator mode to run arbitrary terminal-based
programs from within Emacs.  You open a terminal emulator buffer using
@kbd{M-x term}, with an extra carriage return to accept the default shell
(such as @command{bash}).  (Incidentally, don't confuse this command with @kbd{M-x
terminal-emulator}, which starts an older terminal emulator mode not
supported by Emacspeak.)

Three kinds of commands are used within the terminal emulator.  Normal
term commands use a prefix of @kbd{C-c}.  The emacspeak commands for
eterm mode use a prefix of @kbd{C-t}.  Anything else is a normal shell
command.

There are two sub-modes of term mode: char sub-mode and line sub-mode.
In char sub-mode, emacspeak will only speak the final chunk of output
@MDash{} typically the last line displayed.  Each character typed
(except `term-escape-char`) is sent immediately.  Use char sub-mode
for screen oriented programs like @command{vi} or @command{pine}.

In line sub-mode, program output is spoken if user option
@code{eterm-autospeak} is turned on.  When you type a return at the
end of the buffer, that line is sent as input, while return not at end
copies the rest of the line to the end and sends it.  When using
terminal line mode with option @code{eterm-autospeak} turned on,
speech feedback is similar to that obtained in regular
@code{shell-mode} buffers.

The default is char sub-mode.  You can switch to line sub-mode with
@kbd{C-c C-j} (recall that control J is a linefeed), and back to char
sub-mode with @kbd{C-c C-k} (think of character spelled with a K).

Note: Use char-mode with the terminal emulator for running
screen-oriented programs like Lynx or Pine.  For regular shell
interaction just use @kbd{M-x shell} instead of using the terminal
emulator.

@section Char Sub-mode of Term Mode

In char sub-mode of term, each character you type is sent directly to
the inferior process without intervention from emacs, except for the
escape character (usually @kbd{C-c}).

Here are some of the useful commands for the char sub-mode.  Note that
the usual commands for killing a buffer or switching buffers do not work
in this mode, so new key bindings are supplied.  The first five commands
are different ways of leaving this mode.

@table @kbd
@item C-c C-j
@kindex C-c C-j
@itemx M-x term-line-mode
@findex M-x term-line-mode
Switch to line sub-mode of term mode.

@item C-c o
@kindex C-c o
@itemx M-x other-window
Select the next window on this frame.  All windows on current frame
are arranged in a cyclic order.  This command selects the next window
in that order.  If there are no other windows, this command does
nothing.

@item C-c C-f
@kindex C-c C-f
@itemx M-x find-file
Switch to a buffer visiting a file, creating one if none already exists.

@item C-c 0
@kindex C-c 0
@itemx M-x delete-window
Remove current window from the display.

@item C-c k
@kindex C-c k
@itemx M-x kill-buffer
Kill the current buffer.

@item C-c C-x C-c
@kindex C-c C-x C-c
@itemx M-x save-buffers-kill-emacs
Offer to save each buffer, then kill this Emacs process.

@item C-c C-d
@kindex C-c C-d
@itemx M-x list-directory
Display a list of files in or matching DIRNAME, a la `ls'.  DIRNAME is
globbed by the shell if necessary.  Prefix arg (@kbd{C-u}) means supply -l
switch to @command{ls}.  The list appears in a second window.

@item C-c 1
@kindex C-c 1
@itemx M-x delete-other-windows
Delete all other windows in the frame, making the current window fill
its frame.

@item C-c C-c
@kindex C-c C-c
@itemx M-x term-send-raw
Send the last character typed through the terminal-emulator
without any interpretation.

@item C-c (
@kindex C-c (
@itemx M-x start-kbd-macro
Record subsequent keyboard input, defining a keyboard macro.  The
commands are recorded even as they are executed.  Use @kbd{C-c )} to finish
recording and make the macro available.  Use @kbd{M-x name-last-kbd-macro}
to give it a permanent name.  Prefix arg (@kbd{C-u}) means append to last
macro defined; This begins by re-executing that macro as if you had
typed it again.

@item C-c )
@kindex C-c )
@itemx M-x end-kbd-macro
Finish defining a keyboard macro.  The definition was started by
@kbd{C-c (}.  The macro is now available for use via @kbd{C-c e}, or
it can be given a name with @kbd{M-x name-last-kbd-macro} and then
invoked under that name.

@item C-c e
@kindex C-c e
@itemx M-x call-last-kbd-macro
Call the last keyboard macro that you defined with @kbd{C-c (}.  A
prefix argument serves as a repeat count.  Zero means repeat until
error.
@end table

You can get a list of all the key sequences with a C-c prefix by typing
@kbd{C-c C-h} while in this sub-mode.  Some of those commands are only available
in the char sub-mode, while others are generally available.

@section Line Sub-mode of Term Mode

In line sub-mode of term mode, emacs editing commands work normally,
until you type @key{RETURN} which sends the current line to the inferior process.

Here are some of the useful commands for the line sub-mode of the term
mode.  In addition, the usual commands for handling a buffer work in
this mode (@kbd{C-x o} to switch windows, @kbd{C-x k} to kill a
buffer, @kbd{C-x f} to find a file, and so forth).

@table @kbd
@item C-c C-k
@kindex C-c C-k
@itemx M-x term-char-mode
Switch to char sub-mode of term mode.

@item C-c C-z
@kindex C-c C-z
@itemx M-x term-stop-subjob
Stop the current subjob.  Resume the subjob in the foreground with the
ordinary command @command{fg}, or run it in the background with
@command{bg}.  WARNING: if there is no current subjob, you can end up
suspending the top-level process running in the buffer.  If you
accidentally do this, use @kbd{M-x term-continue-subjob} to resume the
process.  (This is not a problem with most shells, including
@command{bash}, since they ignore this signal.)

@item C-c C-\
@kindex C-c C-\
@itemx M-x term-quit-subjob
Send quit signal to the current subjob.

@item C-c C-c
@kindex C-c C-c
@itemx M-x term-interrupt-subjob
Interrupt the current subjob.

@item C-c C-w
@kindex C-c C-w
@itemx M-x backward-kill-word
Kill characters backward until encountering the end of a word.

@item C-c C-u
@kindex C-c C-u
@itemx M-x term-kill-input
Kill all text from last stuff output by interpreter to point.

@item C-c C-a
@kindex C-c C-a
@itemx M-x term-bol
Goes to the beginning of line, then skips past the prompt, if any.
If a prefix argument is given (@kbd{C-u}), then no prompt skip
@MDash{} go straight to column 0.

@item C-c C-d
@kindex C-c C-d
@itemx M-x term-send-eof
Send an end of file character (EOF) to the current buffer's process.
@end table

You can get a list of all the key sequences with a @kbd{C-c} prefix by
typing @kbd{C-c C-h} while in this sub-mode.  Some of those commands
are only available in the line sub-mode, while others are generally
available.

@section Eterm Mode Commands

The eterm mode maintains a pointer, which is not necessarily the same
as the terminal's cursor.  It is intended to be used in eterm's char
submode.  In char submode, @kbd{C-t ,} (that's control-t followed by
comma) will tell you where the eterm pointer is.  @kbd{C-t C-i} will
tell you where the terminal's cursor is.  The top left corner of the
window is "row 0 column 0".

The eterm pointer can be moved with @kbd{C-t <} (to the top of the
screen), @kbd{C-t >} (to the bottom of the screen), @kbd{C-t n} (to
the next line), @kbd{C-t p} (to the previous line), and @kbd{C-t .}
(to the cursor).  Each of these also speaks the line the pointer moves
to.  You can also search forward with @kbd{C-t s}.
@c , or search backward with @kbd{C-t r}.

These commands speak without moving the pointer: @kbd{C-t l} (current
line), @kbd{C-t w} (current word), @kbd{C-t c} (current character),
and @kbd{C-t @key{SPACE}} (from eterm pointer to cursor).

You may enter review mode with @kbd{C-t q}.  In review mode, you can
search the buffer and speak its contents, without disturbing the
terminal.  Commands for moving the pointer are similar to normal
editing commands, but without a control key: @kbd{n} and @kbd{p} for
next and previous line, @kbd{f} and @kbd{b} for forward and back by
characters, @kbd{<} and @kbd{>} for the beginning or end of the
buffer.  @kbd{c}, @kbd{w}, and @kbd{l} speak the current character,
word, and line.  @kbd{s} searches forward (not incrementally).  A
comma speaks the pointer location.  A period moves the pointer to the
terminal cursor.  Return to normal term mode by typing @kbd{q}.
