@c $Id: eterm.texi,v 15.0 2001/11/20 20:05:31 raman Exp $

@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
M-x term, with an extra carriage return to accept the default shell
(such as bash).  (Incidently, don't confuse this command with 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 C-c.  The emacspeak commands for
eterm mode use a prefix of 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
--typically the last line displayed.
Each character typed (except `term-escape-char`) is sent immediately.
Use char sub-mode for screen oriented programs like vi or 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 C-c
C-j (recall that control J is a linefeed), and back to char sub-mode
with 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 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 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 @samp
@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 (C-u) means supply -l
switch to `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 C-c ) to finish recording and make the macro available.
Use M-x name-last-kbd-macro to give it a permanent name.
Prefix arg (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 C-c (.
The macro is now available for use via C-c e,
or it can be given a name with 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 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
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 RET 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 (C-x o to switch windows, C-x k to kill a buffer, C-x f to
find a file, and so forth).

@table @samp
@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 fg, or run it in the background with 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 M-x
term-continue-subjob to resume the process. (This is not a problem with
with most shells, including 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 (C-u), then no prompt skip
-- 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 C-c prefix by typing
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, C-t , (that's control-t followed by comma)
will tell you where the eterm pointer is.  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 C-t < (to the top of the screen),
C-t > (to the bottom of the screen), C-t n (to the next line), C-t p (to
the previous line), and C-t . (to the cursor).  Each of these also
speaks the line the pointer moves to.  You can also search forward with
C-t s.  
@c , or search backwards with C-t r.

These commands speak without moving the pointer: C-t l (current line),
C-t w (current word), C-t c (current character), and C-t [space] (from
eterm pointer to cursor).

You may enter review mode with 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: n and p for next and previous line, f and b
for forward and back by characters, < and > for the beginning or end of
the buffer.  c, w, and l speak the current character, word, and line.  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 q.