d08e9679 |
1 | .TH pterm 1 |
2 | .UC |
3 | .SH NAME |
4 | pterm \- yet another X terminal emulator |
5 | .SH SYNOPSIS |
6 | \fBpterm\fP [ \fIoptions\fP ] |
7 | .SH DESCRIPTION |
8 | \fIpterm\fP is a terminal emulator for X. It is based on a port of |
9 | the terminal emulation engine in the Windows SSH client PuTTY. |
10 | .SH OPTIONS |
11 | The command-line options supported by \fIpterm\fP are: |
12 | .IP "\fB-e\fP \fIcommand\fP [ \fIarguments\fP ]" |
13 | Specify a command to be executed in the new terminal. Everything on |
14 | the command line after this option will be passed straight to the |
15 | \fIexecvp\fP system call; so if you need the command to redirect its |
16 | input or output, you will have to use \fIsh\fP: |
17 | |
18 | pterm -e sh -c 'mycommand < inputfile' |
19 | .IP "\fB--display\fP \fIdisplay-name\fP" |
20 | Specify the X display on which to open \fIpterm\fP. (Note this |
21 | option has a double minus sign, even though none of the others do. |
22 | This is because this option is supplied automatically by GTK. |
23 | Sorry.) |
24 | .IP "\fB-name\fP \fIfont-name\fP" |
25 | Specify the name under which \fIpterm\fP looks up X resources. |
26 | Normally it will look them up as (for example) \fBpterm.Font\fP. If |
27 | you specify "-name xyz", it will look them up as \fBxyz.Font\fP |
28 | instead. This allows you to set up several different sets of |
29 | defaults and choose between them. |
30 | .IP "\fB-fn\fP \fIfont-name\fP" |
31 | Specify the font to use for normal text displayed in the terminal. |
32 | .IP "\fB-fb\fP \fIfont-name\fP" |
33 | Specify the font to use for bold text displayed in the terminal. If |
34 | the \fIBoldAsColour\fP resource is set to 1 (the default), bold text |
35 | will be displayed in different colours instead of a different font, |
36 | so this option will be ignored. If \fIBoldAsColour\fP is set to 0 |
37 | and you do not specify a bold font, \fIpterm\fP will overprint the |
38 | normal font to make it look bolder. |
39 | .IP "\fB-geometry\fP \fIwidth\fPx\fIheight\fP" |
40 | Specify the size of the terminal, in rows and columns of text. |
41 | Unfortunately \fIpterm\fP does not currently support specifying the |
42 | initial position of the window. |
43 | .IP "\fB-sl\fP \fIlines\fP" |
44 | Specify the number of lines of scrollback to save off the top of the |
45 | terminal. |
46 | .IP "\fB-fg\fP \fIcolour\fP" |
47 | Specify the foreground colour to use for normal text. |
48 | .IP "\fB-bg\fP \fIcolour\fP" |
49 | Specify the background colour to use for normal text. |
50 | .IP "\fB-bfg\fP \fIcolour\fP" |
51 | Specify the foreground colour to use for bold text, if the |
52 | \fIBoldAsColour\fP resource is set to 1 (the default). |
53 | .IP "\fB-bbg\fP \fIcolour\fP" |
54 | Specify the foreground colour to use for bold reverse-video text, if |
55 | the \fIBoldAsColour\fP resource is set to 1 (the default). (This |
56 | colour is best thought of as the bold version of the background |
57 | colour; so it only appears when text is displayed \fIin\fP the |
58 | background colour.) |
59 | .IP "\fB-cfg\fP \fIcolour\fP" |
60 | Specify the foreground colour to use for text covered by the cursor. |
61 | .IP "\fB-cbg\fP \fIcolour\fP" |
62 | Specify the background colour to use for text covered by the cursor. |
63 | In other words, this is the main colour of the cursor. |
64 | .IP "\fB-T\fP \fItitle\fP" |
65 | Specify the initial title of the terminal window. (This can be |
66 | changed under control of the server.) |
67 | .IP "\fB-ut-\fP or \fB+ut\fP" |
68 | Tells \fIpterm\fP not to record your login in the \fIutmp\fP, |
69 | \fIwtmp\fP and \fIlastlog\fP system log files; so you will not show |
70 | up on \fIfinger\fP or \fIwho\fP listings, for example. |
71 | .IP "\fB-ut\fP" |
72 | Tells \fIpterm\fP to record your login in \fIutmp\fP, \fIwtmp\fP and |
73 | \fIlastlog\fP: this is the opposite of \fI-ut-\fP. This is the |
74 | default option: you will probably only need to specify it explicitly |
75 | if you have changed the default using the \fIStampUtmp\fP resource. |
76 | .IP "\fB-ls-\fP or \fB+ls\fP" |
77 | Tells \fIpterm\fP not to execute your shell as a login shell. |
78 | .IP "\fB-ls\fP" |
79 | Tells \fIpterm\fP to execute your shell as a login shell: this is |
80 | the opposite of \fI-ls-\fP. This is the default option: you will |
81 | probably only need to specify it explicitly if you have changed the |
82 | default using the \fILoginShell\fP resource. |
83 | .IP "\fB-sb-\fP or \fB+sb\fP" |
84 | Tells \fIpterm\fP not to display a scroll bar. |
85 | .IP "\fB-sb\fP" |
86 | Tells \fIpterm\fP to display a scroll bar: this is the opposite of |
86f2f4f8 |
87 | \fI-sb-\fP. This is the default option: you will probably only need |
d08e9679 |
88 | to specify it explicitly if you have changed the default using the |
89 | \fIScrollBar\fP resource. |
90 | .IP "\fB-log\fP \fIfilename\fP" |
91 | This option makes \fIpterm\fP log all the terminal output to a file |
92 | as well as displaying it in the terminal. |
93 | .IP "\fB-nethack\fP" |
94 | Tells \fIpterm\fP to enable NetHack keypad mode, in which the |
95 | numeric keypad generates the NetHack "hjklyubn" direction keys. This |
96 | enables you to play NetHack with the numeric keypad without having |
97 | to use the NetHack "number_pad" option (which requires you to press |
98 | "n" before any repeat count). So you can move with the numeric |
99 | keypad, and enter repeat counts with the normal number keys. |
0ac15bdc |
100 | .IP "\fB-xrm\fP \fIresource-string\fP" |
101 | This option specifies an X resource string. Useful for setting |
102 | resources which do not have their own command-line options. For |
103 | example: |
104 | |
105 | pterm -xrm 'ScrollbarOnLeft: 1' |
96add444 |
106 | .IP "\fB-help\fP, \fB--help\fP" |
107 | Display a message summarizing the available options |
d08e9679 |
108 | .SH X RESOURCES |
109 | \fIpterm\fP can be more completely configured by means of X |
110 | resources. All of these resources are of the form \fIpterm.FOO\fP |
111 | for some FOO; you can make \fIpterm\fP look them up under another |
112 | name, such as \fIxyz.FOO\fP, by specifying the command-line option |
113 | "-name xyz". |
90cfd8f4 |
114 | .IP "\fBpterm.CloseOnExit\fP" |
461b078e |
115 | This option should be set to 0, 1 or 2; the default is 2. It |
90cfd8f4 |
116 | controls what \fIpterm\fP does when the process running inside it |
461b078e |
117 | terminates. When set to 2 (the default), \fIpterm\fP will close its |
118 | window as soon as the process inside it terminates. When set to 0, |
119 | \fIpterm\fP will print the process's exit status, and the window |
120 | will remain present until a key is pressed (allowing you to inspect |
121 | the scrollback, and copy and paste text out of it). |
90cfd8f4 |
122 | |
461b078e |
123 | When this setting is set to 1, \fIpterm\fP will close |
90cfd8f4 |
124 | immediately if the process exits cleanly (with an exit status of |
125 | zero), but the window will stay around if the process exits with a |
126 | non-zero code or on a signal. This enables you to see what went |
127 | wrong if the process suffers an error, but not to have to bother |
128 | closing the window in normal circumstances. |
d08e9679 |
129 | .IP "\fBpterm.TerminalType\fP" |
130 | This controls the value set in the TERM environment variable inside |
131 | the new terminal. The default is "xterm". |
132 | .IP "\fBpterm.BackspaceIsDelete\fP" |
133 | This option should be set to either 0 or 1; the default is 1. When |
134 | set to 0, the ordinary Backspace key generates the Backspace |
135 | character (^H); when set to 1, it generates the Delete character |
136 | (^?). Whichever one you set, the terminal device inside \fIpterm\fP |
137 | will be set up to expect it. |
138 | .IP "\fBpterm.RXVTHomeEnd\fP" |
139 | This option should be set to either 0 or 1; the default is 0. When |
140 | it is set to 1, the Home and End keys generate the control sequences |
141 | they would generate in the \fIrxvt\fP terminal emulator, instead of |
142 | the more usual ones generated by other emulators. |
143 | .IP "\fBpterm.LinuxFunctionKeys\fP" |
144 | This option can be set to any number between 0 and 5 inclusive; the |
145 | default is 0. The modes vary the control sequences sent by the |
146 | function keys; for more complete documentation, it is probably |
147 | simplest to try each option in "pterm -e cat", and press the keys to |
148 | see what they generate. |
149 | .IP "\fBpterm.NoApplicationKeys\fP" |
150 | This option should be set to either 0 or 1; the default is 0. When |
151 | set to 1, it stops the server from ever switching the numeric keypad |
152 | into application mode (where the keys send function-key-like |
153 | sequences instead of numbers or arrow keys). You probably only need |
154 | this if some application is making a nuisance of itself. |
155 | .IP "\fBpterm.NoApplicationCursors\fP" |
156 | This option should be set to either 0 or 1; the default is 0. When |
157 | set to 1, it stops the server from ever switching the cursor keys |
158 | into application mode (where the keys send slightly different |
159 | sequences). You probably only need this if some application is |
160 | making a nuisance of itself. |
161 | .IP "\fBpterm.NoMouseReporting\fP" |
162 | This option should be set to either 0 or 1; the default is 0. When |
163 | set to 1, it stops the server from ever enabling mouse reporting |
164 | mode (where mouse clicks are sent to the application instead of |
165 | controlling cut and paste). |
166 | .IP "\fBpterm.NoRemoteResize\fP" |
167 | This option should be set to either 0 or 1; the default is 0. When |
168 | set to 1, it stops the server from being able to remotely control |
169 | the size of the \fIpterm\fP window. |
170 | .IP "\fBpterm.NoAltScreen\fP" |
171 | This option should be set to either 0 or 1; the default is 0. When |
172 | set to 1, it stops the server from using the "alternate screen" |
173 | terminal feature, which lets full-screen applications leave the |
174 | screen exactly the way they found it. |
175 | .IP "\fBpterm.NoRemoteWinTitle\fP" |
176 | This option should be set to either 0 or 1; the default is 0. When |
177 | set to 1, it stops the server from remotely controlling the title of |
178 | the \fIpterm\fP window. |
179 | .IP "\fBpterm.NoDBackspace\fP" |
180 | This option should be set to either 0 or 1; the default is 0. When |
181 | set to 1, it disables the normal action of the Delete (^?) character |
182 | when sent from the server to the terminal, which is to move the |
183 | cursor left by one space and erase the character now under it. |
184 | .IP "\fBpterm.ApplicationCursorKeys\fP" |
185 | This option should be set to either 0 or 1; the default is 0. When |
186 | set to 1, the default initial state of the cursor keys are |
187 | application mode (where the keys send function-key-like sequences |
188 | instead of numbers or arrow keys). When set to 0, the default state |
189 | is the normal one. |
190 | .IP "\fBpterm.ApplicationKeypad\fP" |
191 | This option should be set to either 0 or 1; the default is 0. When |
192 | set to 1, the default initial state of the numeric keypad is |
193 | application mode (where the keys send function-key-like sequences |
194 | instead of numbers or arrow keys). When set to 0, the default state |
195 | is the normal one. |
196 | .IP "\fBpterm.NetHackKeypad\fP" |
197 | This option should be set to either 0 or 1; the default is 0. When |
198 | set to 1, the numeric keypad operates in NetHack mode. This is |
199 | equivalent to the \fI-nethack\fP command-line option. |
200 | .IP "\fBpterm.Answerback\fP" |
201 | This option controls the string which the terminal sends in response |
202 | to receiving the ^E character ("tell me about yourself"). By default |
203 | this string is "PuTTY". |
204 | .IP "\fBpterm.HideMousePtr\fP" |
205 | This option should be set to either 0 or 1; the default is 0. When |
206 | it is set to 1, the mouse pointer will disappear if it is over the |
207 | \fIpterm\fP window and you press a key. It will reappear as soon as |
208 | you move it. |
209 | .IP "\fBpterm.WindowBorder\fP" |
210 | This option controls the number of pixels of space between the text |
211 | in the \fIpterm\fP window and the window frame. The default is 1. |
212 | You can increase this value, but decreasing it to 0 is not |
213 | recommended because it can cause the window manager's size hints to |
214 | work incorrectly. |
215 | .IP "\fBpterm.CurType\fP" |
216 | This option should be set to either 0, 1 or 2; the default is 0. |
217 | When set to 0, the text cursor displayed in the window is a |
218 | rectangular block. When set to 1, the cursor is an underline; when |
219 | set to 2, it is a vertical line. |
220 | .IP "\fBpterm.BlinkCur\fP" |
221 | This option should be set to either 0 or 1; the default is 0. When |
222 | it is set to 1, the text cursor will blink when the window is active. |
223 | .IP "\fBpterm.Beep\fP" |
224 | This option should be set to either 0 or 2 (yes, 2); the default is |
225 | 0. When it is set to 2, \fIpterm\fP will respond to a bell character |
226 | (^G) by flashing the window instead of beeping. |
227 | .IP "\fBpterm.BellOverload\fP" |
228 | This option should be set to either 0 or 1; the default is 0. When |
229 | it is set to 1, \fIpterm\fP will watch out for large numbers of |
230 | bells arriving in a short time and will temporarily disable the bell |
231 | until they stop. The idea is that if you \fIcat\fP a binary file, |
232 | the frantic beeping will mostly be silenced by this feature and will |
233 | not drive you crazy. |
234 | |
235 | The bell overload mode is activated by receiving N bells in time T; |
236 | after a further time S without any bells, overload mode will turn |
237 | itself off again. |
2cb50250 |
238 | |
239 | Bell overload mode is always deactivated by any keypress in the |
240 | terminal. This means it can respond to large unexpected streams of |
241 | data, but does not interfere with ordinary command-line activities |
242 | that generate beeps (such as filename completion). |
d08e9679 |
243 | .IP "\fBpterm.BellOverloadN\fP" |
244 | This option counts the number of bell characters which will activate |
245 | bell overload if they are received within a length of time T. The |
246 | default is 5. |
247 | .IP "\fBpterm.BellOverloadT\fP" |
248 | This option specifies the time period in which receiving N or more |
249 | bells will activate bell overload mode. It is measured in |
250 | microseconds, so (for example) set it to 1000000 for one second. The |
251 | default is 2000000 (two seconds). |
252 | .IP "\fBpterm.BellOverloadS\fP" |
253 | This option specifies the time period of silence required to turn |
254 | off bell overload mode. It is measured in microseconds, so (for |
255 | example) set it to 1000000 for one second. The default is 5000000 |
256 | (five seconds of silence). |
257 | .IP "\fBpterm.ScrollbackLines\fP" |
258 | This option specifies how many lines of scrollback to save above the |
259 | visible terminal screen. The default is 200. This resource is |
260 | equivalent to the \fI-sl\fP command-line option. |
261 | .IP "\fBpterm.DECOriginMode\fP" |
262 | This option should be set to either 0 or 1; the default is 0. It |
263 | specifies the default state of DEC Origin Mode. (If you don't know |
264 | what that means, you probably don't need to mess with it.) |
265 | .IP "\fBpterm.AutoWrapMode\fP" |
266 | This option should be set to either 0 or 1; the default is 1. It |
267 | specifies the default state of auto wrap mode. When set to 1, very |
268 | long lines will wrap over to the next line on the terminal; when set |
269 | to 0, long lines will be squashed against the right-hand edge of the |
270 | screen. |
271 | .IP "\fBpterm.LFImpliesCR\fP" |
272 | This option should be set to either 0 or 1; the default is 0. When |
273 | set to 1, the terminal will return the cursor to the left side of |
274 | the screen when it receives a line feed character. |
275 | .IP "\fBpterm.WinTitle\fP" |
276 | This resource is the same as the \fI-T\fP command-line option: it |
277 | controls the initial title of the window. The default is "pterm". |
278 | .IP "\fBpterm.TermWidth\fP" |
279 | This resource is the same as the width part of the \fI-geometry\fP |
280 | command-line option: it controls the number of columns of text in |
281 | the window. The default is 80. |
282 | .IP "\fBpterm.TermHeight\fP" |
283 | This resource is the same as the width part of the \fI-geometry\fP |
284 | command-line option: it controls the number of columns of text in |
285 | the window. The defaults is 24. |
286 | .IP "\fBpterm.Font\fP" |
287 | This resource is the same as the \fI-fn\fP command-line option: it |
288 | controls the font used to display normal text. The default is |
289 | "fixed". |
290 | .IP "\fBpterm.BoldFont\fP" |
291 | This resource is the same as the \fI-fb\fP command-line option: it |
292 | controls the font used to display bold text when \fIBoldAsColour\fP |
293 | is turned off. The default is unset (the font will be bolded by |
294 | printing it twice at a one-pixel offset). |
12994a99 |
295 | .IP "\fBpterm.ShadowBoldOffset\fP" |
296 | This resource can be set to an integer; the default is -1. It |
297 | specifies the offset at which text is overprinted when using "shadow |
298 | bold" mode. The default (-1) means that the text will be printed in |
299 | the normal place, and also one character to the left; this seems to |
300 | work well for most X bitmap fonts, which have a blank line of pixels |
301 | down the left-hand side. For some fonts, you may need to set this to |
302 | +1, so that the text is overprinted one pixel to the right; for |
303 | really large fonts, you may want to set it even higher. |
d08e9679 |
304 | .IP "\fBpterm.BoldAsColour\fP" |
305 | This option should be set to either 0 or 1; the default is 1. It |
306 | specifies the default state of auto wrap mode. When set to 1, bold |
307 | text is shown by displaying it in a brighter colour; when set to 0, |
308 | bold text is shown by displaying it in a heavier font. |
309 | .IP "\fBpterm.Colour0\fP, \fBpterm.Colour1\fP, ..., \fBpterm.Colour21\fP" |
310 | These options control the various colours used to display text in |
311 | the \fIpterm\fP window. Each one should be specified as a triple of |
312 | decimal numbers giving red, green and blue values: so that black is |
313 | "0,0,0", white is "255,255,255", red is "255,0,0" and so on. |
314 | |
315 | Colours 0 and 1 specify the foreground colour and its bold |
316 | equivalent (the \fI-fg\fP and \fI-bfg\fP command-line options). |
317 | Colours 2 and 3 specify the background colour and its bold |
318 | equivalent (the \fI-bg\fP and \fI-bbg\fP command-line options). |
319 | Colours 4 and 5 specify the text and block colours used for the |
320 | cursor (the \fI-cfg\fP and \fI-cbg\fP command-line options). Each |
321 | even number from 6 to 20 inclusive specifies the colour to be used |
322 | for one of the ANSI primary colour specifications (black, red, |
323 | green, yellow, blue, magenta, cyan, white, in that order); the odd |
324 | numbers from 7 to 21 inclusive specify the bold version of each |
325 | colour, in the same order. The defaults are: |
326 | |
327 | .nf |
328 | pterm.Colour0: 187,187,187 |
329 | pterm.Colour1: 255,255,255 |
330 | pterm.Colour2: 0,0,0 |
331 | pterm.Colour3: 85,85,85 |
332 | pterm.Colour4: 0,0,0 |
333 | pterm.Colour5: 0,255,0 |
334 | pterm.Colour6: 0,0,0 |
335 | pterm.Colour7: 85,85,85 |
336 | pterm.Colour8: 187,0,0 |
337 | pterm.Colour9: 255,85,85 |
338 | pterm.Colour10: 0,187,0 |
339 | pterm.Colour11: 85,255,85 |
340 | pterm.Colour12: 187,187,0 |
341 | pterm.Colour13: 255,255,85 |
342 | pterm.Colour14: 0,0,187 |
343 | pterm.Colour15: 85,85,255 |
344 | pterm.Colour16: 187,0,187 |
345 | pterm.Colour17: 255,85,255 |
346 | pterm.Colour18: 0,187,187 |
347 | pterm.Colour19: 85,255,255 |
348 | pterm.Colour20: 187,187,187 |
349 | pterm.Colour21: 255,255,255 |
350 | .fi |
351 | .IP "\fBpterm.RectSelect\fP" |
352 | This option should be set to either 0 or 1; the default is 0. When |
353 | set to 0, dragging the mouse over several lines selects to the end |
354 | of each line and from the beginning of the next; when set to 1, |
355 | dragging the mouse over several lines selects a rectangular region. |
356 | In each case, holding down Alt while dragging gives the other |
357 | behaviour. |
358 | .IP "\fBpterm.MouseOverride\fP" |
359 | This option should be set to either 0 or 1; the default is 1. When |
360 | set to 1, if the application requests mouse tracking (so that mouse |
361 | clicks are sent to it instead of doing selection), holding down |
362 | Shift will revert the mouse to normal selection. When set to 0, |
363 | mouse tracking completely disables selection. |
364 | .IP "\fBpterm.Printer\fP" |
365 | This option is unset by default. If you set it, then |
366 | server-controlled printing is enabled: the server can send control |
367 | sequences to request data to be sent to a printer. That data will be |
368 | piped into the command you specify here; so you might want to set it |
369 | to "lpr", for example, or "lpr -Pmyprinter". |
370 | .IP "\fBpterm.ScrollBar\fP" |
371 | This option should be set to either 0 or 1; the default is 1. When |
372 | set to 0, the scrollbar is hidden (although Shift-PageUp and |
373 | Shift-PageDown still work). This is the same as the \fI-sb\fP |
374 | command-line option. |
375 | .IP "\fBpterm.ScrollbarOnLeft\fP" |
376 | This option should be set to either 0 or 1; the default is 0. When |
377 | set to 1, the scrollbar will be displayed on the left of the |
378 | terminal instead of on the right. |
379 | .IP "\fBpterm.ScrollOnKey\fP" |
380 | This option should be set to either 0 or 1; the default is 0. When |
381 | set to 1, any keypress causes the position of the scrollback to be |
382 | reset to the very bottom. |
383 | .IP "\fBpterm.ScrollOnDisp\fP" |
384 | This option should be set to either 0 or 1; the default is 1. When |
385 | set to 1, any activity in the display causes the position of the |
386 | scrollback to be reset to the very bottom. |
387 | .IP "\fBpterm.BCE\fP" |
388 | This option should be set to either 0 or 1; the default is 1. When |
389 | set to 1, the various control sequences that erase parts of the |
390 | terminal display will erase in whatever the current background |
391 | colour is; when set to 0, they will erase in black always. |
392 | .IP "\fBpterm.BlinkText\fP" |
393 | This option should be set to either 0 or 1; the default is 0. When |
394 | set to 1, text specified as blinking by the server will actually |
395 | blink on and off; when set to 0, \fIpterm\fP will use the less |
396 | distracting approach of making the text's background colour bold. |
397 | .IP "\fBpterm.StampUtmp\fP" |
398 | This option should be set to either 0 or 1; the default is 1. When |
399 | set to 1, \fIpterm\fP will log the login in the various system log |
400 | files. This resource is equivalent to the \fI-ut\fP command-line |
401 | option. |
402 | .IP "\fBpterm.LoginShell\fP" |
403 | This option should be set to either 0 or 1; the default is 1. When |
404 | set to 1, \fIpterm\fP will execute your shell as a login shell. This |
405 | resource is equivalent to the \fI-ls\fP command-line option. |
406 | .SH BUGS |
407 | Most of the X resources have silly names. (Historical reasons from |
408 | PuTTY, mostly.) |
409 | |
410 | Character-set switching and Unicode are not yet supported. |