1 ba19f6b5 2004-04-19 devnull .TH 9TERM 1
3 ba19f6b5 2004-04-19 devnull 9term, label \- terminal windows
4 ba19f6b5 2004-04-19 devnull .SH SYNOPSIS
20 ba19f6b5 2004-04-19 devnull .SH DESCRIPTION
22 ba19f6b5 2004-04-19 devnull is a terminal window program for the X Window System,
23 ba19f6b5 2004-04-19 devnull providing an interface similar to that used on Plan 9.
24 ba19f6b5 2004-04-19 devnull .SS Commands
27 ba19f6b5 2004-04-19 devnull command starts a new window.
31 ba19f6b5 2004-04-19 devnull flag causes button 2 to send the selection immediately, like acme.
32 ba19f6b5 2004-04-19 devnull Otherwise button 2 brings up a menu, described below.
36 ba19f6b5 2004-04-19 devnull option initializes windows so that text scrolls;
37 ba19f6b5 2004-04-19 devnull the default is not to scroll.
41 ba19f6b5 2004-04-19 devnull argument to
43 ba19f6b5 2004-04-19 devnull names a font used to display text, both in
44 ba19f6b5 2004-04-19 devnull .IR 9term 's
46 ba19f6b5 2004-04-19 devnull and as a default for any programs running in its windows; it also
47 ba19f6b5 2004-04-19 devnull establishes the
48 ba19f6b5 2004-04-19 devnull environment variable
49 ba19f6b5 2004-04-19 devnull .BR $font .
52 ba19f6b5 2004-04-19 devnull is not given,
54 ba19f6b5 2004-04-19 devnull uses the imported value of
56 ba19f6b5 2004-04-19 devnull if set; otherwise it uses the graphics system default.
59 ba19f6b5 2004-04-19 devnull runs the given command in the window, or
60 ba19f6b5 2004-04-19 devnull .B $SHELL
61 ba19f6b5 2004-04-19 devnull if no command is given.
65 ba19f6b5 2004-04-19 devnull command changes a window's identifying name by
66 ba19f6b5 2004-04-19 devnull echoing a special control code that both
69 ba19f6b5 2004-04-19 devnull .IR xterm (1)
70 ba19f6b5 2004-04-19 devnull understand.
71 ba19f6b5 2004-04-19 devnull .SS Text windows
72 ba19f6b5 2004-04-19 devnull Characters typed on the keyboard
73 ba19f6b5 2004-04-19 devnull collect in the window to form
74 ba19f6b5 2004-04-19 devnull a long, continuous document.
76 ba19f6b5 2004-04-19 devnull There is always some
77 ba19f6b5 2004-04-19 devnull .I selected
78 ba19f6b5 2004-04-19 devnull .IR text ,
79 ba19f6b5 2004-04-19 devnull a contiguous string marked on the screen by reversing its color.
80 ba19f6b5 2004-04-19 devnull If the selected text is a null string, it is indicated by a hairline cursor
81 ba19f6b5 2004-04-19 devnull between two characters.
82 ba19f6b5 2004-04-19 devnull The selected text
83 ba19f6b5 2004-04-19 devnull may be edited by mousing and typing.
84 ba19f6b5 2004-04-19 devnull Text is selected by pointing and clicking button 1
85 ba19f6b5 2004-04-19 devnull to make a null-string selection, or by pointing,
86 ba19f6b5 2004-04-19 devnull then sweeping with button 1 pressed.
87 ba19f6b5 2004-04-19 devnull Text may also be selected by double-clicking:
88 ba19f6b5 2004-04-19 devnull just inside a matched delimiter-pair
89 ba19f6b5 2004-04-19 devnull with one of
90 ba19f6b5 2004-04-19 devnull .B {[(<`'"
91 ba19f6b5 2004-04-19 devnull on the left and
92 ba19f6b5 2004-04-19 devnull .B }])>`'"
93 ba19f6b5 2004-04-19 devnull on the right, it selects all text within
94 ba19f6b5 2004-04-19 devnull the pair; at the beginning
95 ba19f6b5 2004-04-19 devnull or end of a line, it selects the line; within or at the edge of an alphanumeric word,
96 ba19f6b5 2004-04-19 devnull it selects the word.
98 ba19f6b5 2004-04-19 devnull Characters typed on the keyboard replace the selected text;
99 ba19f6b5 2004-04-19 devnull if this text is not empty, it is placed in a
100 ba19f6b5 2004-04-19 devnull .I snarf buffer
101 ba19f6b5 2004-04-19 devnull common to all windows but distinct from that of
102 ba19f6b5 2004-04-19 devnull .IR sam (1).
104 ba19f6b5 2004-04-19 devnull Programs access the text in the window at a single point
105 ba19f6b5 2004-04-19 devnull maintained automatically by
106 ba19f6b5 2004-04-19 devnull .IR 9term .
108 ba19f6b5 2004-04-19 devnull .I output point
109 ba19f6b5 2004-04-19 devnull is the location in the text where the next character written by
110 ba19f6b5 2004-04-19 devnull a program to the terminal
111 ba19f6b5 2004-04-19 devnull will appear; afterwards, the output point is the null string
112 ba19f6b5 2004-04-19 devnull beyond the new character.
113 ba19f6b5 2004-04-19 devnull The output point is also the location in the text of the next character
114 ba19f6b5 2004-04-19 devnull that will be read (directly from the text in the window,
115 ba19f6b5 2004-04-19 devnull not from an intervening buffer)
116 ba19f6b5 2004-04-19 devnull by a program.
117 ba19f6b5 2004-04-19 devnull Since Unix does not make it possible to know when a program
118 ba19f6b5 2004-04-19 devnull is reading the terminal, lines are sent as they are completed
119 ba19f6b5 2004-04-19 devnull (when the user types a newline character).
121 ba19f6b5 2004-04-19 devnull In general there is text in the window after the output point,
122 ba19f6b5 2004-04-19 devnull usually placed there by typing but occasionally by the editing
123 ba19f6b5 2004-04-19 devnull operations described below.
124 ba19f6b5 2004-04-19 devnull A pending read of the terminal
125 ba19f6b5 2004-04-19 devnull will block until the text after the output point contains
126 ba19f6b5 2004-04-19 devnull a newline, whereupon the read may
127 ba19f6b5 2004-04-19 devnull acquire the text, up to and including the newline.
128 ba19f6b5 2004-04-19 devnull After the read, as described above, the output point will be at
129 ba19f6b5 2004-04-19 devnull the beginning of the next line of text.
130 ba19f6b5 2004-04-19 devnull In normal circumstances, therefore, typed text is delivered
131 ba19f6b5 2004-04-19 devnull to programs a line at a time.
132 ba19f6b5 2004-04-19 devnull Changes made by typing or editing before the text is read will not
133 ba19f6b5 2004-04-19 devnull be seen by the program reading it.
134 ba19f6b5 2004-04-19 devnull Because of the Unix issues mentioned above, a line of text is only editable
135 ba19f6b5 2004-04-19 devnull until it is completed with a newline character, or when hold mode
136 ba19f6b5 2004-04-19 devnull (see below) is enabled.
138 ba19f6b5 2004-04-19 devnull Even when there are newlines in the output text,
139 ba19f6b5 2004-04-19 devnull .I 9term
140 ba19f6b5 2004-04-19 devnull will not honor reads if the window is in
142 ba19f6b5 2004-04-19 devnull .IR mode ,
143 ba19f6b5 2004-04-19 devnull which is indicated by a white cursor and blue text and border.
144 ba19f6b5 2004-04-19 devnull The ESC character toggles hold mode.
145 ba19f6b5 2004-04-19 devnull Some programs
146 ba19f6b5 2004-04-19 devnull automatically turn on hold mode to simplify the editing of multi-line text;
147 ba19f6b5 2004-04-19 devnull type ESC when done to allow
149 ba19f6b5 2004-04-19 devnull to read the text.
151 ba19f6b5 2004-04-19 devnull An EOT character (control-D) behaves exactly like newline except
152 ba19f6b5 2004-04-19 devnull that it is not delivered to a program when read.
153 ba19f6b5 2004-04-19 devnull Thus on an empty line an EOT serves to deliver an end-of-file indication:
154 ba19f6b5 2004-04-19 devnull the read will return zero characters.
155 ba19f6b5 2004-04-19 devnull Like newlines, unread EOTs may be successfully edited out of the text.
156 ba19f6b5 2004-04-19 devnull The BS character (control-H) erases the character before the selected text.
157 ba19f6b5 2004-04-19 devnull The ETB character (control-W) erases any nonalphanumeric characters, then
158 ba19f6b5 2004-04-19 devnull the alphanumeric word just before the selected text.
159 ba19f6b5 2004-04-19 devnull `Alphanumeric' here means non-blanks and non-punctuation.
160 ba19f6b5 2004-04-19 devnull The NAK character (control-U) erases the text after the output point,
161 ba19f6b5 2004-04-19 devnull and not yet read by a program, but not more than one line.
162 ba19f6b5 2004-04-19 devnull All these characters are typed on the keyboard and hence replace
163 ba19f6b5 2004-04-19 devnull the selected text; for example, typing a BS with a word selected
164 ba19f6b5 2004-04-19 devnull places the word in the snarf buffer, removes it from the screen,
165 ba19f6b5 2004-04-19 devnull and erases the character before the word.
167 ba19f6b5 2004-04-19 devnull An ACK character (control-F) or Insert character triggers file name completion
168 ba19f6b5 2004-04-19 devnull for the preceding string (see
169 ba19f6b5 2004-04-19 devnull .IR complete (3)).
171 ba19f6b5 2004-04-19 devnull Text may be moved vertically within the window.
172 ba19f6b5 2004-04-19 devnull A scroll bar on the left of the window shows in its clear portion what fragment of the
173 ba19f6b5 2004-04-19 devnull total output text is visible on the screen, and in its gray part what
174 ba19f6b5 2004-04-19 devnull is above or below view;
175 ba19f6b5 2004-04-19 devnull it measures characters, not lines.
176 ba19f6b5 2004-04-19 devnull Mousing inside the scroll bar moves text:
177 ba19f6b5 2004-04-19 devnull clicking button 1 with the mouse pointing inside the scroll bar
178 ba19f6b5 2004-04-19 devnull brings the line at the top of the
179 ba19f6b5 2004-04-19 devnull window to the cursor's vertical location;
180 ba19f6b5 2004-04-19 devnull button 3 takes the line at the cursor to the top of the window;
181 ba19f6b5 2004-04-19 devnull button 2, treating the scroll bar as a ruler, jumps to the indicated portion
182 ba19f6b5 2004-04-19 devnull of the stored text.
183 ba19f6b5 2004-04-19 devnull Holding a button pressed in the scroll bar will cause the text
184 ba19f6b5 2004-04-19 devnull to scroll continuously until the button is released.
186 ba19f6b5 2004-04-19 devnull Typing down-arrow scrolls forward
187 ba19f6b5 2004-04-19 devnull one third of a window, and up-arrow scrolls back.
188 ba19f6b5 2004-04-19 devnull Typing page-down scrolls forward
189 ba19f6b5 2004-04-19 devnull two thirds of a window, and page-up scrolls back.
190 ba19f6b5 2004-04-19 devnull Typing Home scrolls to the top of the window;
191 ba19f6b5 2004-04-19 devnull typing End scrolls to the end.
193 ba19f6b5 2004-04-19 devnull The DEL character sends an
194 ba19f6b5 2004-04-19 devnull .L interrupt
195 ba19f6b5 2004-04-19 devnull note to all processes in the window's process group.
196 ba19f6b5 2004-04-19 devnull Unlike the other characters, the DEL and arrow
197 ba19f6b5 2004-04-19 devnull keys do not affect the selected text.
198 ba19f6b5 2004-04-19 devnull The left (right) arrow key moves the selection to one character
199 ba19f6b5 2004-04-19 devnull before (after) the current selection.
201 ba19f6b5 2004-04-19 devnull .I 9term
202 ba19f6b5 2004-04-19 devnull relies on the kernel's terminal processing to handle
203 ba19f6b5 2004-04-19 devnull EOT and DEL, so the terminal must be set up with EOT
204 ba19f6b5 2004-04-19 devnull as the ``eof'' character and DEL as the ``intr'' character.
206 ba19f6b5 2004-04-19 devnull Normally, written output to a window blocks when
207 ba19f6b5 2004-04-19 devnull the text reaches the end of the screen and the terminal
208 ba19f6b5 2004-04-19 devnull buffer fills;
209 ba19f6b5 2004-04-19 devnull a button 2 menu item toggles scrolling.
211 ba19f6b5 2004-04-19 devnull .I 9term
212 ba19f6b5 2004-04-19 devnull changes behavior according to
213 ba19f6b5 2004-04-19 devnull the terminal settings of the running programs.
214 ba19f6b5 2004-04-19 devnull Most programs run with echo enabled.
215 ba19f6b5 2004-04-19 devnull In this mode,
216 ba19f6b5 2004-04-19 devnull .I 9term
217 ba19f6b5 2004-04-19 devnull display and allows editing of the input.
218 ba19f6b5 2004-04-19 devnull Some programs, typically those reading passwords,
219 ba19f6b5 2004-04-19 devnull run with echo disabled.
220 ba19f6b5 2004-04-19 devnull In this mode,
221 ba19f6b5 2004-04-19 devnull .I 9term
222 ba19f6b5 2004-04-19 devnull passes keystrokes through directly, without
223 ba19f6b5 2004-04-19 devnull echoing them or buffering until a newline character.
224 ba19f6b5 2004-04-19 devnull These heuristics work well in many cases, but there
225 ba19f6b5 2004-04-19 devnull are a few common ones where they fall short.
226 ba19f6b5 2004-04-19 devnull First, programs using the GNU readline library typically
227 ba19f6b5 2004-04-19 devnull disable terminal echo and perform echoing themselves.
228 ba19f6b5 2004-04-19 devnull The most common example is the shell
229 ba19f6b5 2004-04-19 devnull .IR bash (1).
230 ba19f6b5 2004-04-19 devnull Disabling the use of readline with
231 ba19f6b5 2004-04-19 devnull .RB `` "set +o emacs" ''
232 ba19f6b5 2004-04-19 devnull .RI [ sic ]
233 ba19f6b5 2004-04-19 devnull usually restores the desired behavior.
234 ba19f6b5 2004-04-19 devnull Second, remote terminal programs such as
235 ba19f6b5 2004-04-19 devnull .IR ssh (1)
236 ba19f6b5 2004-04-19 devnull typically run with echo disabled, relying on the
237 ba19f6b5 2004-04-19 devnull remote system to echo characters as desired.
238 ba19f6b5 2004-04-19 devnull Plan 9's
242 ba19f6b5 2004-04-19 devnull flag to disable this, leaving the terminal in ``cooked'' mode.
243 ba19f6b5 2004-04-19 devnull For similar situations on Unix,
244 ba19f6b5 2004-04-19 devnull .IR 9term 's
245 ba19f6b5 2004-04-19 devnull button 2 menu has an entry to toggle the forced use of
246 ba19f6b5 2004-04-19 devnull cooked mode, despite the terminal settings.
247 ba19f6b5 2004-04-19 devnull In such cases, it is useful to run
248 ba19f6b5 2004-04-19 devnull .RB `` "stty -echo" ''
249 ba19f6b5 2004-04-19 devnull on the remote system to avoid seeing your input twice.
251 ba19f6b5 2004-04-19 devnull Editing operations are selected from a menu on button 2.
254 ba19f6b5 2004-04-19 devnull operation deletes the selected text
255 ba19f6b5 2004-04-19 devnull from the screen and puts it in the snarf buffer;
256 ba19f6b5 2004-04-19 devnull .B snarf
257 ba19f6b5 2004-04-19 devnull copies the selected text to the buffer without deleting it;
258 ba19f6b5 2004-04-19 devnull .B paste
259 ba19f6b5 2004-04-19 devnull replaces the selected text with the contents of the buffer;
262 ba19f6b5 2004-04-19 devnull copies the snarf buffer to just after the output point, adding a final newline
263 ba19f6b5 2004-04-19 devnull if missing.
264 ba19f6b5 2004-04-19 devnull .B Paste
265 ba19f6b5 2004-04-19 devnull will sometimes and
267 ba19f6b5 2004-04-19 devnull will always place text after the output point; the text so placed
268 ba19f6b5 2004-04-19 devnull will behave exactly as described above. Therefore when pasting
269 ba19f6b5 2004-04-19 devnull text containing newlines after the output point, it may be prudent
270 ba19f6b5 2004-04-19 devnull to turn on hold mode first.
273 ba19f6b5 2004-04-19 devnull .B plumb
274 ba19f6b5 2004-04-19 devnull menu item sends the contents of the selection (not the snarf buffer) to the
275 ba19f6b5 2004-04-19 devnull .IR plumber (1).
276 ba19f6b5 2004-04-19 devnull If the selection is empty, it sends the white-space-delimited text
277 ba19f6b5 2004-04-19 devnull containing the selection (typing cursor).
278 ba19f6b5 2004-04-19 devnull A typical use of this feature is to tell the editor to find the source of an error
279 ba19f6b5 2004-04-19 devnull by plumbing the file and line information in a compiler's diagnostic.
280 ba19f6b5 2004-04-19 devnull .SH SOURCE
281 ba19f6b5 2004-04-19 devnull .B /usr/local/plan9/src/cmd/9term
282 ba19f6b5 2004-04-19 devnull .SH BUGS
283 ba19f6b5 2004-04-19 devnull There should be a program to toggle the current window's hold mode.
285 ba19f6b5 2004-04-19 devnull Unix makes everything harder.
