t9term.1 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
t9term.1 (10587B)
---
1 .TH 9TERM 1
2 .SH NAME
3 9term \- terminal windows
4 .SH SYNOPSIS
5 .B 9term
6 [
7 .B -asc
8 ]
9 [
10 .B -f
11 .I font
12 ]
13 [
14 .I cmd
15 \&...
16 ]
17 .SH DESCRIPTION
18 .I 9term
19 is a terminal window program for the X Window System,
20 providing an interface similar to that used on Plan 9.
21 .SS Command
22 The
23 .I 9term
24 command starts a new window.
25 .PP
26 The
27 .B -a
28 flag causes button 2 to send the selection immediately, like acme.
29 Otherwise button 2 brings up a menu, described below.
30 .PP
31 The
32 .B -s
33 option has no effect. It formerly set the scrolling mode,
34 and is recognized to avoid breaking scripts that create new windows.
35 See below for a description of scrolling behavior.
36 .PP
37 The
38 .B -c
39 option starts the window in forced cooked mode,
40 described below.
41 .PP
42 The
43 .I font
44 argument to
45 .B -f
46 names a font used to display text, both in
47 .IR 9term 's
48 menus
49 and as a default for any programs running in its windows; it also
50 establishes the
51 environment variable
52 .BR $font .
53 If
54 .B -f
55 is not given,
56 .I 9term
57 uses the imported value of
58 .B $font
59 if set; otherwise it uses the graphics system default.
60 (See
61 .MR font (7)
62 for a full discussion of font syntaxes.)
63 .PP
64 .I 9term
65 runs the given command in the window, or
66 .B $SHELL
67 if no command is given.
68 .SS Text windows
69 Characters typed on the keyboard
70 collect in the window to form
71 a long, continuous document.
72 .PP
73 There is always some
74 .I selected
75 .IR text ,
76 a contiguous string marked on the screen by reversing its color.
77 If the selected text is a null string, it is indicated by a hairline cursor
78 between two characters.
79 The selected text
80 may be edited by mousing and typing.
81 Text is selected by pointing and clicking button 1
82 to make a null-string selection, or by pointing,
83 then sweeping with button 1 pressed.
84 Text may also be selected by double-clicking:
85 just inside a matched delimiter-pair
86 with one of
87 .B {[(<`'"
88 on the left and
89 .B }])>`'"
90 on the right, it selects all text within
91 the pair; at the beginning
92 or end of a line, it selects the line; within or at the edge of an alphanumeric word,
93 it selects the word.
94 .PP
95 Characters typed on the keyboard replace the selected text;
96 if this text is not empty, it is placed in a
97 .I snarf buffer
98 common to all windows but distinct from that of
99 .MR sam (1) .
100 .PP
101 Programs access the text in the window at a single point
102 maintained automatically by
103 .IR 9term .
104 The
105 .I output point
106 is the location in the text where the next character written by
107 a program to the terminal
108 will appear; afterwards, the output point is the null string
109 beyond the new character.
110 The output point is also the location in the text of the next character
111 that will be read (directly from the text in the window,
112 not from an intervening buffer)
113 by a program.
114 Since Unix does not make it possible to know when a program
115 is reading the terminal, lines are sent as they are completed
116 (when the user types a newline character).
117 .PP
118 In general there is text in the window after the output point,
119 usually placed there by typing but occasionally by the editing
120 operations described below.
121 A pending read of the terminal
122 will block until the text after the output point contains
123 a newline, whereupon the read may
124 acquire the text, up to and including the newline.
125 After the read, as described above, the output point will be at
126 the beginning of the next line of text.
127 In normal circumstances, therefore, typed text is delivered
128 to programs a line at a time.
129 Changes made by typing or editing before the text is read will not
130 be seen by the program reading it.
131 Because of the Unix issues mentioned above, a line of text is only editable
132 until it is completed with a newline character, or when hold mode
133 (see below) is enabled.
134 .PP
135 Even when there are newlines in the output text,
136 .I 9term
137 will not honor reads if the window is in
138 .I hold
139 .IR mode ,
140 which is indicated by a white cursor and blue text and border.
141 The ESC character toggles hold mode.
142 Some programs
143 automatically turn on hold mode to simplify the editing of multi-line text;
144 type ESC when done to allow
145 .I mail
146 to read the text.
147 .PP
148 An EOT character (control-D) behaves exactly like newline except
149 that it is not delivered to a program when read.
150 Thus on an empty line an EOT serves to deliver an end-of-file indication:
151 the read will return zero characters.
152 .\" Like newlines, unread EOTs may be successfully edited out of the text.
153 The BS character (control-H) erases the character before the selected text.
154 The ETB character (control-W) erases any nonalphanumeric characters, then
155 the alphanumeric word just before the selected text.
156 `Alphanumeric' here means non-blanks and non-punctuation.
157 The NAK character (control-U) erases the text after the output point,
158 and not yet read by a program, but not more than one line.
159 All these characters are typed on the keyboard and hence replace
160 the selected text; for example, typing a BS with a word selected
161 places the word in the snarf buffer, removes it from the screen,
162 and erases the character before the word.
163 .PP
164 An ACK character (control-F) or Insert character triggers file name completion
165 for the preceding string (see
166 .MR complete (3) ).
167 .PP
168 Text may be moved vertically within the window.
169 A scroll bar on the left of the window shows in its clear portion what fragment of the
170 total output text is visible on the screen, and in its grey part what
171 is above or below view;
172 it measures characters, not lines.
173 Mousing inside the scroll bar moves text:
174 clicking button 1 with the mouse pointing inside the scroll bar
175 brings the line at the top of the
176 window to the cursor's vertical location;
177 button 3 takes the line at the cursor to the top of the window;
178 button 2, treating the scroll bar as a ruler, jumps to the indicated portion
179 of the stored text.
180 Holding a button pressed in the scroll bar will cause the text
181 to scroll continuously until the button is released.
182 .PP
183 Typing down-arrow scrolls forward
184 one third of a window, and up-arrow scrolls back.
185 Typing page-down scrolls forward
186 two thirds of a window, and page-up scrolls back.
187 Typing Home scrolls to the top of the window;
188 typing End scrolls to the end.
189 .PP
190 The DEL character sends an
191 .L interrupt
192 note to all processes in the window's process group.
193 Unlike the other characters, the DEL and arrow
194 keys do not affect the selected text.
195 The left (right) arrow key moves the selection to one character
196 before (after) the current selection.
197 .PP
198 .I 9term
199 relies on the kernel's terminal processing to handle
200 EOT, so the terminal must be set up with EOT
201 as the ``eof'' character.
202 .I 9term
203 runs
204 .MR stty (1)
205 to establish this when the terminal is created.
206 .PP
207 .I 9term
208 always treats the DEL keystroke as an interrupt request.
209 In response it sends the terminal's current interrupt character
210 (which need not be DEL).
211 .PP
212 Written output to a window is appended to the end of the window.
213 The window scrolls to display the new output only if the
214 end of the window was visible before the write.
215 .PP
216 .I 9term
217 changes behavior according to
218 the terminal settings of the running programs.
219 Most programs run with echo enabled.
220 In this mode,
221 .I 9term
222 displays and allows editing of the input.
223 Some programs, typically those reading passwords,
224 run with echo disabled.
225 In this mode,
226 .I 9term
227 passes keystrokes through directly, without
228 echoing them or buffering until a newline character.
229 These heuristics work well in many cases, but there
230 are a few common ones where they fall short.
231 First, programs using the GNU readline library typically
232 disable terminal echo and perform echoing themselves.
233 The most common example is the shell
234 .MR bash (1) .
235 Disabling the use of readline with
236 .RB `` "set +o emacs" ''
237 .RI [ sic ]
238 usually restores the desired behavior.
239 Second, remote terminal programs such as
240 .MR ssh (1)
241 typically run with echo disabled, relying on the
242 remote system to echo characters as desired.
243 Plan 9's
244 .I ssh
245 has a
246 .B -C
247 flag to disable this, leaving the terminal in ``cooked'' mode.
248 For similar situations on Unix,
249 .IR 9term 's
250 button 2 menu has an entry to toggle the forced use of
251 cooked mode, despite the terminal settings.
252 In such cases, it is useful to run
253 .RB `` "stty -echo" ''
254 on the remote system to avoid seeing your input twice.
255 .PP
256 Editing operations are selected from a menu on button 2.
257 The
258 .B cut
259 operation deletes the selected text
260 from the screen and puts it in the snarf buffer;
261 .B snarf
262 copies the selected text to the buffer without deleting it;
263 .B paste
264 replaces the selected text with the contents of the buffer;
265 and
266 .B send
267 copies the snarf buffer to just after the output point, adding a final newline
268 if missing.
269 .B Paste
270 will sometimes and
271 .B send
272 will always place text after the output point; the text so placed
273 will behave exactly as described above. Therefore when pasting
274 text containing newlines after the output point, it may be prudent
275 to turn on hold mode first.
276 .PP
277 The
278 .B plumb
279 menu item sends the contents of the selection (not the snarf buffer) to the
280 .I plumber
281 (see
282 .MR plumb (1) ).
283 If the selection is empty, it sends the white-space-delimited text
284 containing the selection (typing cursor).
285 A typical use of this feature is to tell the editor to find the source of an error
286 by plumbing the file and line information in a compiler's diagnostic.
287 .PP
288 The
289 .B look
290 menu item searches forward for the contents of the selection within
291 the window. If a match is found, it becomes the new selection and the
292 window scrolls to display it. The search wraps around to the beginning
293 of the windows if the end of the window is reached.
294 .PP
295 For systems without a three-button mouse, the keyboard modifier
296 keys can be used to modify the effect of the main mouse button.
297 On Unix systems, the Control key changes the main button to button 2,
298 and the Alt key changes it to button 3.
299 On Mac systems, the Option key changes the main button to button 2,
300 and the Command key changes it to button 3.
301 Also on Mac systems, the usual keyboard shortcuts
302 Command-C, -V, and -X invoke
303 copy, paste, and cut,
304 as in other programs.
305 .PP
306 Each
307 .I 9term
308 listens for connections on a Unix socket.
309 When a client connects, the
310 .I 9term
311 writes the window contents to the client and then hangs up.
312 .I 9term
313 installs the name of this socket in the environment as
314 .B $text9term
315 before running
316 .IR cmd .
317 .SH SOURCE
318 .B \*9/src/cmd/9term
319 .SH BUGS
320 There should be a program to toggle the current window's hold mode.
321 .PP
322 Not a
323 .IR 9term
324 bug:
325 when running
326 .MR bash (1)
327 in
328 .RB `` "set +o emacs" ''
329 mode, its handling of interrupts is broken.
330 In response to DEL,
331 .I bash
332 processes the interrupt but then silently discards the next
333 character typed.
334 .PP
335 Unix makes everything harder.
336 .SH SEE ALSO
337 .MR wintext (1)