Mercurial > hg > xemacs-beta

comparison man/term.texi @ 0:376386a54a3c r19-14

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