Buildchain fixes and updates from Sebastian

[sxemacs] / info / term.texi

@\input texinfo @c -*-texinfo-*-
settitle Notes about emacs Term mode
@setfilename term.info

@titlepage
@sp 6
@center @titlefont(Notes about Emacs TERM Mode)
@end titlepage

@ifinfo
@dircategory SXEmacs Editor
@direntry
* Term mode: (term).            Emacs terminal emulator mode.
@end direntry
@end ifinfo

@ifnottex
@node Top, , (DIR)
@top Terminal emulator mode
@end ifnottex

This is some notes about the term Emacs mode.

@menu
* term mode::
@end menu

@node term mode
@chapter Term Mode

@menu
* Overview::
* Connecting to remote computers::
* Paging::
* Terminal escapes::
@end menu

The @code{term} package includes the major modes @code{term},
@code{shell}, and @code{gud} (for running gbd or another debugger).
It is a replacement for the comint mode of Emacs 19,
as well as shell, gdb, terminal, and telnet modes.
The package works best with recent releases of Emacs 19,
but will also work reasonably well with Emacs 18 as well as Lucid Emacs 19.

The file @code{nshell.el} is a wrapper to use unless term mode
is built into Emacs.  If works around some of the missing
in older Emacs versions.
To use it, edit the paths in @code{nshell.el}, appropriately,
and then @code{M-x load-file nshell.el RET}.
This will also load in replacement shell and gud modes.

@node Overview
@section Overview

The @code{term} mode is used to control a program (an "inferior process").
It sends most keyboard input characters to the program,
and displays output from the program in the buffer.
This is similar to the traditional comint mode, and
modes derived from it (such as shell and gdb modes).
You can do with the new term-based shell the same sort
of things you could do with the old shell mode,
using more or less the same interface.  However, the
new mode is more flexible, and works somewhat differently.

@menu
* Output from the inferior::
* subbuffer:: The sub-buffer
* altsubbuffer:: The alternate sub-buffer
* Input to the inferior::
@end menu

@node Output from the inferior
@subsection Output from the inferior

In typical usage, output from the inferior is
added to the end of the buffer.  If needed, the window
will be scrolled, just like a regular terminal.
(Only one line at a time will be scrolled, just like
regular terminals, and in contrast to the old shell mode.)
Thus the buffer becomes a log of your interaction with the
inferior, just like the old shell mode.

Like a real terminal, term maintains a "cursor position."
This is the @code{process-mark} of the inferior process.
If the process-mark is not at the end of the buffer, output from
the inferior will overwrite existing text in the buffer.
This is like a real terminal, but unlike the old shell mode
(which inserts the output, instead of overwriting).

Some programs (such as Emacs itself) need to control the
appearance on the screen in detail.  They do this by
sending special control codes.  The exact control
codes needed from terminal to terminal, but nowadays
most terminals and terminal emulators (including xterm)
understand the so-called "ANSI escape sequences" (first
popularized by the Digital's VT100 family of terminal).
The term mode also understands these escape sequences,
and for each control code does the appropriate thing
to change the buffer so that the appearance of the window
will match what it would be on a real terminal.
(In contrast, the old shell mode doesn't handle
terminal control codes at all.)

See <...> for the specific control codes.

@node subbuffer
@subsection The sub-buffer

A program that talks to terminal expects the terminal to have a fixed size. 
If the program is talking a terminal emulator program such as @code{xterm},
that size can be changed (if the xterm window is re-sized), but programs
still assume a logical terminal that has a fixed size independent
of the amount of output transmitted by the programs.

To programs that use it, the Emacs terminal emulator acts as if it
too has a fixed size.  The @dfn{sub-buffer} is the part of a @code{term}-mode
buffer that corresponds to a "normal" terminal.  Most of the time
(unless you explicitly scroll the window displaying the buffer),
the sub-buffer is the part of the buffer that is displayed in a window.

The sub-buffer is defined in terms of three buffer-local-variable:

@defvar term-height
The height of the sub-buffer, in screen lines.
@end defvar

@defvar term-width
The width of the sub-buffer, in screen columns.
@end defvar

@defvar term-home-marker
The "home" position, that is the top left corner of the sub-buffer.
@end defvar

The sub-buffer is assumed to be the end part of the buffer;
the @code{term-home-marker} should never be more than
@code{term-height} screen lines from the end of the buffer.

@node altsubbuffer
@subsection The alternate sub-buffer

When a "graphical" program finishes, it is nice to
restore the screen state to what it was before the program started.
Many people are used to this behavior from @code{xterm}, and
its also offered by the @code{term} emulator.

@defun term-switch-to-alternate-sub-buffer set
If @var{set} is true, and we're not already using the alternate sub-buffer,
switch to it.  What this means is that the @code{term-home-marker}
is saved (in the variable @code{term-saved-home-marker}), and the
@code{term-home-marker} is set to the end of the buffer.

If @var{set} is false and we're using the alternate sub-buffer,
switch back to the saved sub-buffer.  What this means is that the
(current, alternate) sub-buffer is deleted (using
@code{(delete-region term-home-marker (point-max))}), and then the
@code{term-home-marker} is restored (from @code{term-saved-home-marker}).
@end defun

@node Input to the inferior
@subsection Input to the inferior

Characters typed by the user are sent to the inferior.
How this is done depends on whether the @code{term} buffer
is in "character" mode or "line" mode.
(A @code{term} buffer can also be in "pager" mode.
This is discussed <later>.)
Which of these is currently active is specified in the mode line.
The difference between them is the key-bindings available.

In character mode, one character (by default @key{C-c}) is special,
and is a prefix for various commands.  All other characters are
sent directly to the inferior process, with no interpretation by Emacs.
Character mode looks and feels like a real terminal, or a conventional
terminal emulator such as xterm.

In line mode, key commands mostly have standard Emacs actions.
Regulars characters insert themselves into the buffer.
When return is typed, the entire current line of the buffer
(except possibly the prompt) is sent to the inferior process.
Line mode is basically the original shell mode from earlier Emacs versions.

To switch from line mode to character mode type @kbd{C-c C-k}.
To switch from character mode to line mode type @kbd{C-c C-j}.

In&nb