| .TH 9TERM 1 |
| .SH NAME |
| 9term \- terminal windows |
| .SH SYNOPSIS |
| .B 9term |
| [ |
| .B -asc |
| ] |
| [ |
| .B -f |
| .I font |
| ] |
| [ |
| .I cmd |
| \&... |
| ] |
| .SH DESCRIPTION |
| .I 9term |
| is a terminal window program for the X Window System, |
| providing an interface similar to that used on Plan 9. |
| .SS Command |
| The |
| .I 9term |
| command starts a new window. |
| .PP |
| The |
| .B -a |
| flag causes button 2 to send the selection immediately, like acme. |
| Otherwise button 2 brings up a menu, described below. |
| .PP |
| The |
| .B -s |
| option has no effect. It formerly set the scrolling mode, |
| and is recognized to avoid breaking scripts that create new windows. |
| See below for a description of scrolling behavior. |
| .PP |
| The |
| .B -c |
| option starts the window in forced cooked mode, |
| described below. |
| .PP |
| The |
| .I font |
| argument to |
| .B -f |
| names a font used to display text, both in |
| .IR 9term 's |
| menus |
| and as a default for any programs running in its windows; it also |
| establishes the |
| environment variable |
| .BR $font . |
| If |
| .B -f |
| is not given, |
| .I 9term |
| uses the imported value of |
| .B $font |
| if set; otherwise it uses the graphics system default. |
| (See |
| .IR font (7) |
| for a full discussion of font syntaxes.) |
| .PP |
| .I 9term |
| runs the given command in the window, or |
| .B $SHELL |
| if no command is given. |
| .SS Text windows |
| Characters typed on the keyboard |
| collect in the window to form |
| a long, continuous document. |
| .PP |
| There is always some |
| .I selected |
| .IR text , |
| a contiguous string marked on the screen by reversing its color. |
| If the selected text is a null string, it is indicated by a hairline cursor |
| between two characters. |
| The selected text |
| may be edited by mousing and typing. |
| Text is selected by pointing and clicking button 1 |
| to make a null-string selection, or by pointing, |
| then sweeping with button 1 pressed. |
| Text may also be selected by double-clicking: |
| just inside a matched delimiter-pair |
| with one of |
| .B {[(<`'" |
| on the left and |
| .B }])>`'" |
| on the right, it selects all text within |
| the pair; at the beginning |
| or end of a line, it selects the line; within or at the edge of an alphanumeric word, |
| it selects the word. |
| .PP |
| Characters typed on the keyboard replace the selected text; |
| if this text is not empty, it is placed in a |
| .I snarf buffer |
| common to all windows but distinct from that of |
| .IR sam (1). |
| .PP |
| Programs access the text in the window at a single point |
| maintained automatically by |
| .IR 9term . |
| The |
| .I output point |
| is the location in the text where the next character written by |
| a program to the terminal |
| will appear; afterwards, the output point is the null string |
| beyond the new character. |
| The output point is also the location in the text of the next character |
| that will be read (directly from the text in the window, |
| not from an intervening buffer) |
| by a program. |
| Since Unix does not make it possible to know when a program |
| is reading the terminal, lines are sent as they are completed |
| (when the user types a newline character). |
| .PP |
| In general there is text in the window after the output point, |
| usually placed there by typing but occasionally by the editing |
| operations described below. |
| A pending read of the terminal |
| will block until the text after the output point contains |
| a newline, whereupon the read may |
| acquire the text, up to and including the newline. |
| After the read, as described above, the output point will be at |
| the beginning of the next line of text. |
| In normal circumstances, therefore, typed text is delivered |
| to programs a line at a time. |
| Changes made by typing or editing before the text is read will not |
| be seen by the program reading it. |
| Because of the Unix issues mentioned above, a line of text is only editable |
| until it is completed with a newline character, or when hold mode |
| (see below) is enabled. |
| .PP |
| Even when there are newlines in the output text, |
| .I 9term |
| will not honor reads if the window is in |
| .I hold |
| .IR mode , |
| which is indicated by a white cursor and blue text and border. |
| The ESC character toggles hold mode. |
| Some programs |
| automatically turn on hold mode to simplify the editing of multi-line text; |
| type ESC when done to allow |
| .I mail |
| to read the text. |
| .PP |
| An EOT character (control-D) behaves exactly like newline except |
| that it is not delivered to a program when read. |
| Thus on an empty line an EOT serves to deliver an end-of-file indication: |
| the read will return zero characters. |
| .\" Like newlines, unread EOTs may be successfully edited out of the text. |
| The BS character (control-H) erases the character before the selected text. |
| The ETB character (control-W) erases any nonalphanumeric characters, then |
| the alphanumeric word just before the selected text. |
| `Alphanumeric' here means non-blanks and non-punctuation. |
| The NAK character (control-U) erases the text after the output point, |
| and not yet read by a program, but not more than one line. |
| All these characters are typed on the keyboard and hence replace |
| the selected text; for example, typing a BS with a word selected |
| places the word in the snarf buffer, removes it from the screen, |
| and erases the character before the word. |
| .PP |
| An ACK character (control-F) or Insert character triggers file name completion |
| for the preceding string (see |
| .IR complete (3)). |
| .PP |
| Text may be moved vertically within the window. |
| A scroll bar on the left of the window shows in its clear portion what fragment of the |
| total output text is visible on the screen, and in its grey part what |
| is above or below view; |
| it measures characters, not lines. |
| Mousing inside the scroll bar moves text: |
| clicking button 1 with the mouse pointing inside the scroll bar |
| brings the line at the top of the |
| window to the cursor's vertical location; |
| button 3 takes the line at the cursor to the top of the window; |
| button 2, treating the scroll bar as a ruler, jumps to the indicated portion |
| of the stored text. |
| Holding a button pressed in the scroll bar will cause the text |
| to scroll continuously until the button is released. |
| .PP |
| Typing down-arrow scrolls forward |
| one third of a window, and up-arrow scrolls back. |
| Typing page-down scrolls forward |
| two thirds of a window, and page-up scrolls back. |
| Typing Home scrolls to the top of the window; |
| typing End scrolls to the end. |
| .PP |
| The DEL character sends an |
| .L interrupt |
| note to all processes in the window's process group. |
| Unlike the other characters, the DEL and arrow |
| keys do not affect the selected text. |
| The left (right) arrow key moves the selection to one character |
| before (after) the current selection. |
| .PP |
| .I 9term |
| relies on the kernel's terminal processing to handle |
| EOT, so the terminal must be set up with EOT |
| as the ``eof'' character. |
| .I 9term |
| runs |
| .IR stty (1) |
| to establish this when the terminal is created. |
| .PP |
| .I 9term |
| always treats the DEL keystroke as an interrupt request. |
| In response it sends the terminal's current interrupt character |
| (which need not be DEL). |
| .PP |
| Written output to a window is appended to the end of the window. |
| The window scrolls to display the new output only if the |
| end of the window was visible before the write. |
| .PP |
| .I 9term |
| changes behavior according to |
| the terminal settings of the running programs. |
| Most programs run with echo enabled. |
| In this mode, |
| .I 9term |
| displays and allows editing of the input. |
| Some programs, typically those reading passwords, |
| run with echo disabled. |
| In this mode, |
| .I 9term |
| passes keystrokes through directly, without |
| echoing them or buffering until a newline character. |
| These heuristics work well in many cases, but there |
| are a few common ones where they fall short. |
| First, programs using the GNU readline library typically |
| disable terminal echo and perform echoing themselves. |
| The most common example is the shell |
| .IR bash (1). |
| Disabling the use of readline with |
| .RB `` "set +o emacs" '' |
| .RI [ sic ] |
| usually restores the desired behavior. |
| Second, remote terminal programs such as |
| .IR ssh (1) |
| typically run with echo disabled, relying on the |
| remote system to echo characters as desired. |
| Plan 9's |
| .I ssh |
| has a |
| .B -C |
| flag to disable this, leaving the terminal in ``cooked'' mode. |
| For similar situations on Unix, |
| .IR 9term 's |
| button 2 menu has an entry to toggle the forced use of |
| cooked mode, despite the terminal settings. |
| In such cases, it is useful to run |
| .RB `` "stty -echo" '' |
| on the remote system to avoid seeing your input twice. |
| .PP |
| Editing operations are selected from a menu on button 2. |
| The |
| .B cut |
| operation deletes the selected text |
| from the screen and puts it in the snarf buffer; |
| .B snarf |
| copies the selected text to the buffer without deleting it; |
| .B paste |
| replaces the selected text with the contents of the buffer; |
| and |
| .B send |
| copies the snarf buffer to just after the output point, adding a final newline |
| if missing. |
| .B Paste |
| will sometimes and |
| .B send |
| will always place text after the output point; the text so placed |
| will behave exactly as described above. Therefore when pasting |
| text containing newlines after the output point, it may be prudent |
| to turn on hold mode first. |
| .PP |
| The |
| .B plumb |
| menu item sends the contents of the selection (not the snarf buffer) to the |
| .I plumber |
| (see |
| .IR plumb (1)). |
| If the selection is empty, it sends the white-space-delimited text |
| containing the selection (typing cursor). |
| A typical use of this feature is to tell the editor to find the source of an error |
| by plumbing the file and line information in a compiler's diagnostic. |
| .PP |
| Each |
| .I 9term |
| listens for connections on a Unix socket. |
| When a client connects, the |
| .I 9term |
| writes the window contents to the client and then hangs up. |
| .I 9term |
| installs the name of this socket in the environment as |
| .B $text9term |
| before running |
| .IR cmd . |
| .SH SOURCE |
| .B \*9/src/cmd/9term |
| .SH BUGS |
| There should be a program to toggle the current window's hold mode. |
| .PP |
| Not a |
| .IR 9term |
| bug: |
| when running |
| .IR bash (1) |
| in |
| .RB `` "set +o emacs" '' |
| mode, its handling of interrupts is broken. |
| In response to DEL, |
| .I bash |
| processes the interrupt but then silently discards the next |
| character typed. |
| .PP |
| Unix makes everything harder. |
| .SH SEE ALSO |
| .IR wintext (1) |