Mercurial > hg > xemacs-beta

comparison man/term.texi @ 428:3ecd8885ac67 r21-2-22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-22
author cvs
date Mon, 13 Aug 2007 11:28:15 +0200
parents
children 5596b330879a
comparison
equal deleted inserted replaced
427:0a0253eac470 428:3ecd8885ac67
1 @\input texinfo @c -*-texinfo-*-
2 settitle Notes about emacs Term mode
3 @setfilename ../info/term.info
4
5 @titlepage
6 @sp 6
7 @center @titlefont(Notes about Emacs TERM Mode)
8 @end titlepage
9
10 @ifinfo
11 @dircategory XEmacs Editor
12 @direntry
13 * Term mode: (term). Emacs terminal emulator mode.
14 @end direntry
15
16 @node Top, , (DIR)
17 @top Terminal emulator mode
18 @end ifinfo
19
20 This is some notes about the term Emacs mode.
21
22 @menu
23 * term mode::
24 @end menu
25
26 @node term mode
27 @chapter Term Mode
28
29 @menu
30 * Overview::
31 * Connecting to remote computers::
32 * Paging::
33 * Terminal escapes::
34 @end menu
35
36 The @code{term} package includes the major modes @code{term},
37 @code{shell}, and @code{gud} (for running gbd or another debugger).
38 It is a replacement for the comint mode of Emacs 19,
39 as well as shell, gdb, terminal, and telnet modes.
40 The package works best with recent releases of Emacs 19,
41 but will also work reasonably well with Emacs 18 as well as Lucid Emacs 19.
42
43 The file @code{nshell.el} is a wrapper to use unless term mode
44 is built into Emacs. If works around some of the missing
45 in older Emacs versions.
46 To use it, edit the paths in @code{nshell.el}, appropriately,
47 and then @code{M-x load-file nshell.el RET}.
48 This will also load in replacement shell and gud modes.
49
50 @node Overview
51 @section Overview
52
53 The @code{term} mode is used to control a program (an "inferior process").
54 It sends most keyboard input characters to the program,
55 and displays output from the program in the buffer.
56 This is similar to the traditional comint mode, and
57 modes derived from it (such as shell and gdb modes).
58 You can do with the new term-based shell the same sort
59 of things you could do with the old shell mode,
60 using more or less the same interface. However, the
61 new mode is more flexible, and works somewhat differently.
62
63 @menu
64 * Output from the inferior::
65 * subbuffer:: The sub-buffer
66 * altsubbuffer:: The alternate sub-buffer
67 * Input to the inferior::
68 @end menu
69
70 @node Output from the inferior
71 @subsection Output from the inferior
72
73 In typical usage, output from the inferior is
74 added to the end of the buffer. If needed, the window
75 will be scrolled, just like a regular terminal.
76 (Only one line at a time will be scrolled, just like
77 regular terminals, and in contrast to the old shell mode.)
78 Thus the buffer becomes a log of your interaction with the
79 inferior, just like the old shell mode.
80
81 Like a real terminal, term maintains a "cursor position."
82 This is the @code{process-mark} of the inferior process.
83 If the process-mark is not at the end of the buffer, output from
84 the inferior will overwrite existing text in the buffer.
85 This is like a real terminal, but unlike the old shell mode
86 (which inserts the output, instead of overwriting).
87
88 Some programs (such as Emacs itself) need to control the
89 appearance on the screen in detail. They do this by
90 sending special control codes. The exact control
91 codes needed from terminal to terminal, but nowadays
92 most terminals and terminal emulators (including xterm)
93 understand the so-called "ANSI escape sequences" (first
94 popularized by the Digital's VT100 family of terminal).
95 The term mode also understands these escape sequences,
96 and for each control code does the appropriate thing
97 to change the buffer so that the appearance of the window
98 will match what it would be on a real terminal.
99 (In contrast, the old shell mode doesn't handle
100 terminal control codes at all.)
101
102 See <...> for the specific control codes.
103
104 @node subbuffer
105 @subsection The sub-buffer
106
107 A program that talks to terminal expects the terminal to have a fixed size.
108 If the program is talking a terminal emulator program such as @code{xterm},
109 that size can be changed (if the xterm window is re-sized), but programs
110 still assume a logical terminal that has a fixed size independent
111 of the amount of output transmitted by the programs.
112
113 To programs that use it, the Emacs terminal emulator acts as if it
114 too has a fixed size. The @dfn{sub-buffer} is the part of a @code{term}-mode
115 buffer that corresponds to a "normal" terminal. Most of the time
116 (unless you explicitly scroll the window displaying the buffer),
117 the sub-buffer is the part of the buffer that is displayed in a window.
118
119 The sub-buffer is defined in terms of three buffer-local-variable:
120
121 @defvar term-height
122 The height of the sub-buffer, in screen lines.
123 @end defvar
124
125 @defvar term-width
126 The width of the sub-buffer, in screen columns.
127 @end defvar
128
129 @defvar term-home-marker
130 The "home" position, that is the top left corner of the sub-buffer.
131 @end defvar
132
133 The sub-buffer is assumed to be the end part of the buffer;
134 the @code{term-home-marker} should never be more than
135 @code{term-height} screen lines from the end of the buffer.
136
137 @node altsubbuffer
138 @subsection The alternate sub-buffer
139
140 When a "graphical" program finishes, it is nice to
141 restore the screen state to what it was before the program started.
142 Many people are used to this behavior from @code{xterm}, and
143 its also offered by the @code{term} emulator.
144
145 @defun term-switch-to-alternate-sub-buffer set
146 If @var{set} is true, and we're not already using the alternate sub-buffer,
147 switch to it. What this means is that the @code{term-home-marker}
148 is saved (in the variable @code{term-saved-home-marker}), and the
149 @code{term-home-marker} is set to the end of the buffer.
150
151 If @var{set} is false and we're using the alternate sub-buffer,
152 switch back to the saved sub-buffer. What this means is that the
153 (current, alternate) sub-buffer is deleted (using
154 @code{(delete-region term-home-marker (point-max))}), and then the
155 @code{term-home-marker} is restored (from @code{term-saved-home-marker}).
156 @end defun
157
158 @node Input to the inferior
159 @subsection Input to the inferior
160
161 Characters typed by the user are sent to the inferior.
162 How this is done depends on whether the @code{term} buffer
163 is in "character" mode or "line" mode.
164 (A @code{term} buffer can also be in "pager" mode.
165 This is discussed <later>.)
166 Which of these is currently active is specified in the mode line.
167 The difference between them is the key-bindings available.
168
169 In character mode, one character (by default @key{C-c}) is special,
170 and is a prefix for various commands. All other characters are
171 sent directly to the inferior process, with no interpretation by Emacs.
172 Character mode looks and feels like a real terminal, or a conventional
173 terminal emulator such as xterm.
174
175 In line mode, key commands mostly have standard Emacs actions.
176 Regulars characters insert themselves into the buffer.
177 When return is typed, the entire current line of the buffer
178 (except possibly the prompt) is sent to the inferior process.
179 Line mode is basically the original shell mode from earlier Emacs versions.
180
181 To switch from line mode to character mode type @kbd{C-c c}.
182 To switch from character mode to line mode type @kbd{C-c l}.
183
184 In either mode, "echoing" of user input is handled by the inferior.
185 Therefor, in line mode after an input line at the end of the buffer
186 is sent to the inferior, it is deleted from the buffer.
187 This is so that the inferior can echo the input, if it wishes
188 (which it normally does).
189
190 @node Connecting to remote computers
191 @section Connecting to remote computers
192
193 If you want to login to a remove computer, you can do that just as
194 you would expect, using whatever commands you would normally use.
195
196 (This is worth emphasizing, because earlier versions of @code{shell}
197 mode would not work properly if you tried to log in to some other
198 computer, because of the way echoing was handled. That is why
199 there was a separate @code{telnet} mode to partially compensate for
200 these problems. The @code{telnet} mode is no longer needed, and
201 is basically obsolete.)
202
203 A program that asks you for a password will normally suppress
204 echoing of the password, so the password will not show up in the buffer.
205 This will happen just as if you were using a real terminal, if
206 the buffer is in char mode. If it is in line mode, the password
207 will be temporarily visible, but will be erased when you hit return.
208 (This happens automatically; there is no special password processing.)
209
210 When you log in to a different machine, you need to specify the
211 type of terminal your using. If you are talking to a Bourne-compatible
212 shell, and your system understands the @code{TERMCAP} variable,
213 you can use the command @kbd{M-x shell-send-termcap}, which
214 sends a string specifying the terminal type and size.
215 (This command is also useful after the window has changed size.)
216
217 If you need to specify the terminal type manually, you can try the
218 terminal types "ansi" or "vt100".
219
220 You can of course run gdb on that remote computer. One useful
221 trick: If you invoke gdb with the @code{--fullname} option,
222 it will send special commands to Emacs that will cause Emacs to
223 pop up the source files you're debugging. This will work
224 whether or not gdb is running on a different computer than Emacs,
225 assuming can access the source files specified by gdb.
226
227 @node Paging
228 @section Paging
229
230 When the pager is enabled, Emacs will "pause" after each screenful
231 of output (since the last input sent to the inferior).
232 It will enter "pager" mode, which feels a lot like the "more"
233 program: Typing a space requests another screenful of output.
234 Other commands request more or less output, or scroll backwards
235 in the @code{term} buffer. In pager mode, type @kbd{h} or @kbd{?}
236 to display a help message listing all the available pager mode commands.
237
238 In either character or line mode, type @kbd{C-c p} to enable paging,
239 and @kbd{C-c D} to disable it.
240
241 @node Terminal escapes
242 @section Terminal Escape sequences
243
244 A program that does "graphics" on a terminal controls the
245 terminal by sending strings called @dfn{terminal escape sequences}
246 that the terminal (or terminal emulator) interprets as special commands.
247 The @code{term} mode includes a terminal emulator that understands
248 standard ANSI escape sequences, originally popularized by VT100 terminals,
249 and now used by the @code{xterm} program and most modern terminal
250 emulator software.
251
252 @menu
253 * Cursor motion:: Escape sequences to move the cursor
254 * Erasing:: Escape commands for erasing text
255 * Inserting and deleting:: Escape sequences to insert and delete text
256 * Scrolling:: Escape sequences to scroll part of the visible window
257 * Command hook::
258 * Miscellaneous escapes::
259 @end menu
260
261 printing chars
262
263 tab
264
265 LF
266
267 @node Cursor motion
268 @subsection Escape sequences to move the cursor
269
270 @table @kbd
271 @item RETURN
272 Moves to the beginning of the current screen line.
273
274 @item C-b
275 Moves backwards one column. (Tabs are broken up if needed.)
276 @comment Line wrap FIXME
277
278 @item Esc [ R ; C H
279 Move to screen row R, screen column C, where (R=1) is the top row,
280 and (C=1) is the leftmost column. Defaults are R=1 and C=1.
281
282 @item Esc [ N A
283 Move N (default 1) screen lines up.
284 @item Esc [ N B
285 Move N (default 1) screen lines down.
286 @item Esc [ N C
287 Move N (default 1) columns right.
288 @item Esc [ N D
289 Move N (default 1) columns left.
290 @end table
291
292 @node Erasing
293 @subsection Escape commands for erasing text
294
295 These commands "erase" part of the sub-buffer.
296 Erasing means replacing by white space; it is not the same as deleting.
297 The relative screen positions of things that are not erased remain
298 unchanged with each other, as does the relative cursor position.
299
300 @table @kbd
301 @item E [ J
302 Erase from cursor to end of screen.
303 @item E [ 0 J
304 Same as E [ J.
305 @item E [ 1 J
306 Erase from home position to point.
307 @item E [ 2 J
308 Erase whole sub-buffer.
309 @item E [ K
310 Erase from point to end of screen line.
311 @item E [ 0 K
312 Same as E [ K.
313 @item E [ 1 K
314 Erase from beginning of screen line to point.
315 @item E [ 2 K
316 Erase whole screen line.
317 @end table
318
319 @node Inserting and deleting
320 @subsection Escape sequences to insert and delete text
321
322 @table @kbd
323 @item Esc [ N L
324 Insert N (default 1) blank lines.
325 @item Esc [ N M
326 Delete N (default 1) lines.
327 @item Esc [ N P
328 Delete N (default 1) characters.
329 @item Esc [ N @@
330 Insert N (default 1) spaces.
331 @end table
332
333 @node Scrolling
334 @subsection Escape sequences to scroll part of the visible window
335
336 @table @kbd
337 @item Esc D
338 Scroll forward one screen line.
339
340 @item Esc M
341 Scroll backwards one screen line.
342
343 @item Esc [ T ; B r
344 Set the scrolling region to be from lines T down to line B inclusive,
345 where line 1 is the topmost line.
346 @end table
347
348 @node Command hook
349 @subsection Command hook
350
351 If @kbd{C-z} is seen, any text up to a following @key{LF} is scanned.
352 The text in between (not counting the initial C-z or the final LF)
353 is passed to the function that is the value of @code{term-command-hook}.
354
355 The default value of the @code{term-command-hook} variable
356 is the function @code{term-command-hook}, which handles the following:
357
358 @table @kbd
359 @item C-z C-z FILENAME:LINENUMBER:IGNORED LF
360 Set term-pending-frame to @code{(cons "FILENAME" LINENUMBER)}.
361 When the buffer is displayed in the current window, show
362 the FILENAME in the other window, and show an arrow at LINENUMBER.
363 Gdb emits these strings when invoked with the flag --fullname.
364 This is used by gdb mode; you can also invoke gdb with this flag
365 from shell mode.
366
367 @item C-z / DIRNAME LF
368 Set the directory of the term buffer to DIRNAME
369
370 @item C-z ! LEXPR LF
371 Read and evaluate LEXPR as a Lisp expression.
372 The result is ignored.
373 @end table
374
375 @node Miscellaneous escapes
376 @subsection Miscellaneous escapes
377
378 @table @kbd
379 @item C-g (Bell)
380 Calls @code{(beep t)}.
381
382 @item Esc 7
383 Save cursor.
384
385 @item Esc 8
386 Restore cursor.
387
388 @item Esc [ 47 h
389 Switch to the alternate sub-buffer,
390 @item Esc [ 47 l
391 Switch back to the regular sub-buffer,
392 @end table
393
394 @bye